module ti.sysbios.family.arm.m3.Hwi

Cortex M3 Hardware Interrupt Manager

The Cortex M3's Nested Vectored Interrupt Controller (NVIC) supports up to 256 interrupts/exceptions. In practice, most devices support much fewer (ie the Stellaris family of devices have only 80 total interrupts defined). [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/arm/m3/Hwi.xdc
#include <ti/sysbios/family/arm/m3/Hwi.h>
Functions
Void
Void
Void
Void 
Void
Void 
Void 
Void 
Functions common to all IHwi modules
Void 
macro UInt 
UInt 
macro UInt 
UInt 
Bool 
Ptr 
Bool 
Void 
macro Void 
Void 
Void 
Void 
Void 
Functions common to all target instances
Functions common to all target modules
Typedefs
typedef struct
typedef struct
typedef Void 
typedef Void 
typedef Void 
typedef Hwi_Object *
typedef struct
typedef UArg 
typedef enum
typedef struct
typedef struct
typedef struct
typedef struct
typedef Void 
Constants
extern const Assert_Id 
extern const UInt 
extern const Bool 
extern const Bool 
extern const Bool 
extern const Bool 
extern const Hwi_ExcHandlerFuncPtr 
extern const Error_Id 
extern const Error_Id 
extern const Error_Id 
extern const Error_Id 
extern const Error_Id 
extern const Error_Id 
extern const Error_Id 
extern const Error_Id 
extern const Error_Id 
extern const Error_Id 
extern const Error_Id 
extern const Error_Id 
extern const Log_Event 
extern const Log_Event 
extern const Hwi_VectorFuncPtr 
extern const Int 
extern const Int 
extern const UInt 
Variables
 
DETAILS
The Cortex M3's Nested Vectored Interrupt Controller (NVIC) supports up to 256 interrupts/exceptions. In practice, most devices support much fewer (ie the Stellaris family of devices have only 80 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 (ie _c_int00)
IDs 2-14 are hardwired to exceptions.
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 Hwi module supports "zero latency" interrupts. Interrupts configured with priority greater (in actual hardware priority, but lower in number) than Hwi.disablePriority are NOT disabled by Hwi_disable().
Zero latency interrupts are distinguished from regular dispatched interrupts at create time by their priority being greater than 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 M3'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 and Hwi.disablePriority for more details.
INTERRUPT MASKING OPTIONS
The NVIC interrupt controller is designed for priority based interrupts.
In this Hwi module, the maskSetting instance configuration parameter is ignored. Effectively, only the 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).
See the Cortex M3 architecture reference manual for details on the behavior of interrupt priorities and their relationship to the Hwi.priGroup setting.
INTERRUPT VECTOR TABLES
Tiva devices:
By default, two vector tables are created for Tiva devices:
A 16 entry boot vector table is placed at address 0x00000000 in FLASH.
An 80 entry vector table 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 the 16 exception vectors as well as all the 64 user interrupt vectors.
During system startup, the NVIC Vector Table Offset Registor is intialized to point to this vector table after the table has been initialized.
Dual M3 Core ('Ducati') devices:
By default, Ducati core 0 places its runtime vector table at address 0x00000400 and core 1 places its runtime vector table at address 0x00000800.
Additionally, a boot vector table is placed at address 0x00000000 which is shared by both cores.
The boot reset vector function determines which core it is being executed on and jumps to the reset vector contained in its corresponding runtime vector table.
The generation and placement of these vector tables is made automatically when the ti.sysbios.family.arm.ducati.Core module is used.
Although STRONGLY discouraged, this default behavior can be overridden by explicitly setting the Hwi.resetVectorAddress and Hwi.vectorTableAddress config parameters.
RESTRICTIONS
When used within a dual M3 core (Ducati) arrangement, care must be taken when initializing this shared resource. The "Shared Resources" note provided in the ducati package discusses the management of the various hardware and software resources shared by the two M3 cores.

Calling Context

Function Hwi Swi Task Main Startup
clearInterrupt Y Y Y Y Y
create N N Y Y N
disable Y Y Y Y Y
disableInterrupt Y Y Y Y N
enable Y Y Y N N
enableInterrupt Y Y Y Y N
Params_init Y Y Y Y Y
restore Y Y Y Y Y
restoreInterrupt Y Y Y Y Y
construct N N Y Y N
delete N N Y Y N
destruct N N Y Y N
getHookContext Y Y Y Y N
setFunc 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. Hwi_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. Hwi_Module_startupDone() returns FALSE).
 
enum Hwi_MaskingOption

Shorthand interrupt masking options

C synopsis target-domain
typedef enum Hwi_MaskingOption {
    Hwi_MaskingOption_NONE,
    Hwi_MaskingOption_ALL,
    Hwi_MaskingOption_SELF,
    Hwi_MaskingOption_BITMASK,
    Hwi_MaskingOption_LOWER
} Hwi_MaskingOption;
 
VALUES
MaskingOption_NONE — No interrupts are disabled
MaskingOption_ALL — All interrupts are disabled
MaskingOption_SELF — Only this interrupt is disabled
MaskingOption_BITMASK — User supplies interrupt enable 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 Hwi_ExcHandlerFuncPtr

Hwi exception handler function type definition

C synopsis target-domain
typedef Void (*Hwi_ExcHandlerFuncPtr)(UInt*,UInt);
 
 
typedef Hwi_ExceptionHookFuncPtr

Exception hook function type definition

C synopsis target-domain
typedef Void (*Hwi_ExceptionHookFuncPtr)(Hwi_ExcContext*);
 
 
typedef Hwi_FuncPtr

Hwi create function type definition

C synopsis target-domain
typedef Void (*Hwi_FuncPtr)(UArg);
 
 
typedef Hwi_Irp

Interrupt Return Pointer

C synopsis target-domain
typedef UArg Hwi_Irp;
 
DETAILS
This is the address of the interrupted instruction.
 
typedef Hwi_VectorFuncPtr

Hwi vector function type definition

C synopsis target-domain
typedef Void (*Hwi_VectorFuncPtr)(Void);
 
 
struct Hwi_CCR

NVIC Configuration Control Register (CCR)

C synopsis target-domain
typedef struct Hwi_CCR {
    Bits8 STKALIGN;
    // Auto stack alignment in exception
    Bits8 BFHFNMIGN;
    // All faults ignore BUS Faults
    Bits8 DIV_0_TRP;
    // Trap on divide by zero
    Bits8 UNALIGN_TRP;
    // Trap on all unaligned accesses
    Bits8 USERSETMPEND;
    // Allow user to trigger interrupts
    Bits8 NONEBASETHRDENA;
    // Allow entering thread mode anytime
} Hwi_CCR;
 
 
struct Hwi_ExcContext

Exception Context - Register contents at the time of an exception

C synopsis target-domain
typedef struct Hwi_ExcContext {
    BIOS_ThreadType threadType;
    Ptr threadHandle;
    Ptr threadStack;
    SizeT threadStackSize;
    Ptr r0;
    Ptr r1;
    Ptr r2;
    Ptr r3;
    Ptr r4;
    Ptr r5;
    Ptr r6;
    Ptr r7;
    Ptr r8;
    Ptr r9;
    Ptr r10;
    Ptr r11;
    Ptr r12;
    Ptr sp;
    Ptr lr;
    Ptr pc;
    Ptr psr;
    Ptr ICSR;
    Ptr MMFSR;
    Ptr BFSR;
    Ptr UFSR;
    Ptr HFSR;
    Ptr DFSR;
    Ptr MMAR;
    Ptr BFAR;
    Ptr AFSR;
} Hwi_ExcContext;
 
 
struct Hwi_HookSet

Hwi hook set type definition

C synopsis target-domain
typedef struct Hwi_HookSet {
    Void (*registerFxn)(Int);
    Void (*createFxn)(IHwi_Handle,Error_Block*);
    Void (*beginFxn)(IHwi_Handle);
    Void (*endFxn)(IHwi_Handle);
    Void (*deleteFxn)(IHwi_Handle);
} Hwi_HookSet;
 
DETAILS
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.
 
struct Hwi_StackInfo

Structure contains Hwi stack usage info

C synopsis target-domain
typedef struct Hwi_StackInfo {
    SizeT hwiStackPeak;
    SizeT hwiStackSize;
    Ptr hwiStackBase;
} Hwi_StackInfo;
 
DETAILS
Used by getStackInfo() and viewGetStackInfo() functions
 
config Hwi_A_unsupportedMaskingOption  // module-wide

Assert when bad maskSetting parameter provided

C synopsis target-domain
extern const Assert_Id Hwi_A_unsupportedMaskingOption;
 
 
config Hwi_E_NMI  // module-wide

Error raised when NMI exception occurs

C synopsis target-domain
extern const Error_Id Hwi_E_NMI;
 
 
config Hwi_E_alreadyDefined  // module-wide

Error raised when Hwi is already defined

C synopsis target-domain
extern const Error_Id Hwi_E_alreadyDefined;
 
 
config Hwi_E_busFault  // module-wide

Error raised when bus fault exception occurs

C synopsis target-domain
extern const Error_Id Hwi_E_busFault;
 
 
config Hwi_E_debugMon  // module-wide

Error raised when debugMon exception occurs

C synopsis target-domain
extern const Error_Id Hwi_E_debugMon;
 
 
config Hwi_E_exception  // module-wide

Error raised when an exception occurs

C synopsis target-domain
extern const Error_Id Hwi_E_exception;
 
 
config Hwi_E_hardFault  // module-wide

Error raised when hard fault exception occurs

C synopsis target-domain
extern const Error_Id Hwi_E_hardFault;
 
 
config Hwi_E_hwiLimitExceeded  // module-wide

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

C synopsis target-domain
extern const Error_Id Hwi_E_hwiLimitExceeded;
 
 
config Hwi_E_memFault  // module-wide

Error raised when memory fault exception occurs

C synopsis target-domain
extern const Error_Id Hwi_E_memFault;
 
 
config Hwi_E_noIsr  // module-wide

Error raised when an uninitialized interrupt occurs

C synopsis target-domain
extern const Error_Id Hwi_E_noIsr;
 
 
config Hwi_E_reserved  // module-wide

Error raised when reserved exception occurs

C synopsis target-domain
extern const Error_Id Hwi_E_reserved;
 
 
config Hwi_E_svCall  // module-wide

Error raised when svCall exception occurs

C synopsis target-domain
extern const Error_Id Hwi_E_svCall;
 
 
config Hwi_E_usageFault  // module-wide

Error raised when usage fault exception occurs

C synopsis target-domain
extern const Error_Id Hwi_E_usageFault;
 
 
config Hwi_LD_end  // module-wide

Issued just after return from Hwi function (with interrupts disabled)

C synopsis target-domain
extern const Log_Event Hwi_LD_end;
 
 
config Hwi_LM_begin  // module-wide

Issued just prior to Hwi function invocation (with interrupts disabled)

C synopsis target-domain
extern const Log_Event Hwi_LM_begin;
 
 
config Hwi_NUM_INTERRUPTS  // module-wide

The Cortex M3 NVIC supports up to 256 interrupts/exceptions

C synopsis target-domain
extern const Int Hwi_NUM_INTERRUPTS;
 
DETAILS
The actual number supported is device specific and provided by the catalog device specification.
 
config Hwi_NUM_PRIORITIES  // module-wide

The Cortex M3 NVIC supports up to 256 interrupt priorities

C synopsis target-domain
extern const Int Hwi_NUM_PRIORITIES;
 
DETAILS
The actual number supported is device specific and provided by the catalog device specification.
 
config Hwi_disablePriority  // module-wide

The priority that BASEPRI is set to by Hwi_disable()

C synopsis target-domain
extern const UInt Hwi_disablePriority;
 
DETAILS
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().
 
config Hwi_dispatcherAutoNestingSupport  // module-wide

Include interrupt nesting logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherAutoNestingSupport;
 
DETAILS
Default is true.
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 Hwi_dispatcherIrpTrackingSupport  // module-wide

Controls whether the dispatcher retains the interrupted thread's return address

C synopsis target-domain
extern const Bool Hwi_dispatcherIrpTrackingSupport;
 
DETAILS
This option is enabled by default.
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 Hwi_dispatcherSwiSupport  // module-wide

Include Swi scheduling logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherSwiSupport;
 
DETAILS
Default is inherited from BIOS.swiEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that Swis will not be posted from any of their Hwi threads.
WARNING
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Swi scheduler prior to returning from an interrupt. With this setting, Swis MUST NOT be posted from Hwi functions!
 
config Hwi_dispatcherTaskSupport  // module-wide

Include Task scheduling logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherTaskSupport;
 
DETAILS
Default is inherited from BIOS.taskEnabled, which is true by default.
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.
 
config Hwi_excHandlerFunc  // module-wide

Exception handler function pointer

C synopsis target-domain
extern const Hwi_ExcHandlerFuncPtr Hwi_excHandlerFunc;
 
DETAILS
The default is determined by the value of Hwi.enableException.
If the user does NOT set this parameter, then the following default behavior is followed:
If Hwi.enableException is true, then the internal 'Hwi_excHandlerMax' function is used. This exception handler saves the exception context then does a complete exception decode and dump to the console, then raises an Error. The exception context can be viewed within CCS in the ROV Hwi module's Exception view.
If Hwi.enableException is false, then the internal 'Hwi_excHandlerMin' function is used. This exception handler saves the exception context then raises an Error. The exception context can be viewed within CCS in the ROV Hwi module's Exception view.
If the user sets this parameter to their own function, then the user's function will be invoked with the following arguments:
Void myExceptionHandler(UInt *excStack, UInt lr);
Where 'excStack' is the address of the stack containing the register context at the time of the exception, and 'lr' is the link register value when the low-level-assembly-coded exception handler was vectored to.
If this parameter is set to 'null', then an infinite while loop is entered when an exception occurs. This setting minimizes code and data footprint but provides no automatic exception decoding.
 
config Hwi_excHookFunc  // module-wide

User Exception hook function

C synopsis target-domain
extern const Hwi_ExceptionHookFuncPtr Hwi_excHookFunc;
 
DETAILS
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).
 
config Hwi_excHookFuncs  // module-wide
C synopsis target-domain
extern const Hwi_ExceptionHookFuncPtr Hwi_excHookFuncs[];
 
 
config Hwi_nullIsrFunc  // module-wide

Uninitialized ISR Handler. Default is set to an internal exception handler

C synopsis target-domain
extern const Hwi_VectorFuncPtr Hwi_nullIsrFunc;
 
 
config Hwi_priGroup  // module-wide

The PRIGROUP setting. Default is 0

C synopsis target-domain
extern const UInt Hwi_priGroup;
 
DETAILS
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.
 
extern Hwi_nvic

Physical Nested Vectored Interrupt Controller Device. Short name is "Hwi_nvic" Long name is "ti_sysbios_family_arm_m3_Hwi_nvic"

C synopsis target-domain
Hwi_NVIC Hwi_nvic; // linked as extern ti_sysbios_family_arm_m3_Hwi_nvic
 
 
extern Hwi_vnvic

Virtual Nested Vectored Interrupt Controller structure written to by both cores for SMP. Short name is "Hwi_vnvic" Long name is "ti_sysbios_family_arm_m3_Hwi_vnvic"

C synopsis target-domain
Hwi_NVIC Hwi_vnvic; // linked as extern ti_sysbios_family_arm_m3_Hwi_vnvic
 
 
Hwi_clearInterrupt()  // module-wide

Clear a specific interrupt

C synopsis target-domain
Void Hwi_clearInterrupt(UInt intNum);
 
ARGUMENTS
intNum — interrupt number to clear
DETAILS
Clears a specific interrupt's pending status. The implementation is family-specific.
 
Hwi_disable()  // module-wide

Disable all non zero-latency interrupts

C synopsis target-domain
macro UInt Hwi_disable();
 
RETURNS
opaque key for use by Hwi_restore()
DETAILS
Hwi_disable disables all non zero-latency 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.
IMPLEMENTATION NOTE
In order to support zero latency interrupts, rather than setting PRIMASK (which would globally disable all NVIC interrupts), Hwi_disable() instead writes the value of Hwi.disablePriority to the BASEPRI register. In doing so, all interrupts of equal or lower priority than Hwi.disablePriority are disabled.
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.
 
Hwi_disableInterrupt()  // module-wide

Disable a specific interrupt

C synopsis target-domain
UInt Hwi_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.
 
Hwi_enable()  // module-wide

Globally enable interrupts

C synopsis target-domain
macro UInt Hwi_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 SYS/BIOS Startup_POST_APP_MAIN phase.
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 main().
 
Hwi_enableInterrupt()  // module-wide

Enable a specific interrupt

C synopsis target-domain
UInt Hwi_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.
 
Hwi_excSetBuffers()  // module-wide

Set the exception context and stack buffer pointers

C synopsis target-domain
Void Hwi_excSetBuffers(Ptr excContextBuffer, Ptr excStackBuffer);
 
ARGUMENTS
excContextBuffer — Address to place ExcContext
excStackBuffer — Address to place ExcStack
 
Hwi_getCoreStackInfo()  // module-wide

Get Hwi stack usage Info for the specified coreId

C synopsis target-domain
Bool Hwi_getCoreStackInfo(IHwi_StackInfo *stkInfo, Bool computeStackDepth, UInt coreId);
 
ARGUMENTS
stkInfo — pointer to structure of type StackInfo
computeStackDepth — decides whether to compute stack depth
coreId — core whose stack info needs to be retrieved
RETURNS
boolean to indicate a stack overflow
DETAILS
getCoreStackInfo returns the Hwi stack usage info for the specified coreId to its calling function by filling stack base address, stack size and stack peak fields in the StackInfo structure.
This function should be used only in applications built with ti.sysbios.BIOS.smpEnabled set to true.
getCoreStackInfo accepts three arguments, a pointer to a structure of type StackInfo, a boolean and a coreId. 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 getCoreStackInfo() API:
  #include <ti/sysbios/BIOS.h>
  #include <ti/sysbios/hal/Hwi.h>
  #include <ti/sysbios/hal/Core.h>
  #include <ti/sysbios/knl/Task.h>

  ...

  Void idleTask()
  {
      UInt idx;
      Hwi_StackInfo stkInfo;
      Bool stackOverflow = FALSE;

      // Request stack depth for each core's Hwi stack and check for
      // overflow
      for (idx = 0; idx < Core_numCores; idx++) {
          stackOverflow = Hwi_getCoreStackInfo(&stkInfo, TRUE, idx);

          // 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):
          //
          // stackOverflow = Hwi_getCoreStackInfo(&stkInfo, FALSE, idx);

          if (stackOverflow) {
              // isr Stack Overflow detected
          }
      }
  }

  Int main(Int argc, char* argv[])
  {
      ...
      BIOS_start();
      return (0);
  }
 
Hwi_getHandle()  // module-wide

Returns Hwi_handle associated with intNum

C synopsis target-domain
Hwi_Handle Hwi_getHandle(UInt intNum);
 
ARGUMENTS
intNum — interrupt number
 
Hwi_getStackInfo()  // module-wide

Get Hwi stack usage Info

C synopsis target-domain
Bool Hwi_getStackInfo(IHwi_StackInfo *stkInfo, Bool computeStackDepth);
 
ARGUMENTS
stkInfo — pointer to structure of type StackInfo
computeStackDepth — decides whether to compute stack depth
RETURNS
boolean to indicate a stack overflow
DETAILS
getStackInfo returns the Hwi stack usage info to its calling function by filling stack base address, stack size and stack peak fields in the StackInfo structure.
getStackInfo accepts two arguments, a pointer to a structure of type 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/hal/Hwi.h>
  #include <ti/sysbios/knl/Swi.h>
  #include <ti/sysbios/knl/Task.h>

  Swi_Handle swi0;
  volatile Bool swiStackOverflow = FALSE;

  Void swi0Fxn(UArg arg1, UArg 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);
  }
 
Hwi_plug()  // module-wide

Plug a non dispatched interrupt vector with an ISR address

C synopsis target-domain
Void Hwi_plug(UInt intNum, Void *fxn);
 
ARGUMENTS
intNum — interrupt number
fxn — pointer to ISR function
DETAILS
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.
 
Hwi_post()  // module-wide

Generate an interrupt for test purposes

C synopsis target-domain
Void Hwi_post(UInt intNum);
 
ARGUMENTS
intNum — ID of interrupt to generate
 
Hwi_restore()  // module-wide

Globally restore interrupts

C synopsis target-domain
macro Void Hwi_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.
 
Hwi_restoreInterrupt()  // module-wide

Restore a specific interrupt's enabled/disabled state

C synopsis target-domain
Void Hwi_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
 
Hwi_setPriority()  // module-wide

Set an interrupt's relative priority

C synopsis target-domain
Void Hwi_setPriority(UInt intNum, UInt priority);
 
ARGUMENTS
intNum — ID of interrupt
priority — priority
DETAILS
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!
 
Hwi_startup()  // module-wide

Initially enable interrupts

C synopsis target-domain
Void Hwi_startup();
 
DETAILS
Called within BIOS_start
Module-Wide Built-Ins

C synopsis target-domain
Types_ModuleId Hwi_Module_id();
// Get this module's unique id
 
Bool Hwi_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle Hwi_Module_heap();
// The heap from which this module allocates memory
 
Bool Hwi_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 Hwi_Module_getMask();
// Returns the diagnostics mask for this module
 
Void Hwi_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types

C synopsis target-domain
typedef struct Hwi_Object Hwi_Object;
// Opaque internal representation of an instance object
 
typedef Hwi_Object *Hwi_Handle;
// Client reference to an instance object
 
typedef struct Hwi_Struct Hwi_Struct;
// Opaque client structure large enough to hold an instance object
 
Hwi_Handle Hwi_handle(Hwi_Struct *structP);
// Convert this instance structure pointer into an instance handle
 
Hwi_Struct *Hwi_struct(Hwi_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters

C synopsis target-domain
typedef struct Hwi_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 when object is created? Default is true
    Int eventId;
    // Interrupt event ID (Interrupt Selection Number)
    IHwi_MaskingOption maskSetting;
    // Interrupt Masking Option. Only MaskingOption_LOWER is supported
    Int priority;
    // Interrupt priority. The default is 255 which is the lowest priority
    Bool useDispatcher;
    // Use the interrupt dispatcher with this interrupt. Default is true
} Hwi_Params;
 
Void Hwi_Params_init(Hwi_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
 
config Hwi_Params.arg  // instance

ISR function argument. Default is 0

C synopsis target-domain
struct Hwi_Params {
      ...
    UArg arg;
 
 
config Hwi_Params.enableInt  // instance

Enable this interrupt when object is created? Default is true

C synopsis target-domain
struct Hwi_Params {
      ...
    Bool enableInt;
 
 
config Hwi_Params.eventId  // instance

Interrupt event ID (Interrupt Selection Number)

C synopsis target-domain
struct Hwi_Params {
      ...
    Int eventId;
 
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
 
config Hwi_Params.maskSetting  // instance

Interrupt Masking Option. Only MaskingOption_LOWER is supported

C synopsis target-domain
struct Hwi_Params {
      ...
    IHwi_MaskingOption maskSetting;
 
DETAILS
The NVIC interrupt controller is designed for priority based interrupts. No support is provided for anything but Hwi.MaskingOption_LOWER.
 
config Hwi_Params.priority  // instance

Interrupt priority. The default is 255 which is the lowest priority

C synopsis target-domain
struct Hwi_Params {
      ...
    Int priority;
 
DETAILS
The default value of -1 is used as a flag to indicate the lowest (logical) device-specific priority value.
Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
Priority 0 is the highest priority and by default is reserved for zero latency interrupts (see disablePriority).
Valid priorities values are device dependent and their nesting behaviors depend on the priGroup setting.
See the Cortex M3 architecture reference manual for details on the meanings of these parameters.
 
config Hwi_Params.useDispatcher  // instance

Use the interrupt dispatcher with this interrupt. Default is true

C synopsis target-domain
struct Hwi_Params {
      ...
    Bool useDispatcher;
 
DETAILS
If set to false, the interrupt dispatcher is NOT used. Instead, the configured Hwi function address is placed directly in the vector table, which results in the dispatcher being bypassed.
WARNING
Interrupts configured to bupass the dispatcher are not allowed to call ANY SYS/BIOS APIs that effect thread scheduling. Examples of API that should no be invoked are:
Swi_post(),
Semaphore_post(),
Event_post(),
Task_yield()
Additionally, although the signature for a non-dispatched interrupt function is the same as that for a dispatched interrupt (see FuncPtr), no argument is actually passed to the non-dispatched ISR handler.
Runtime Instance Creation

C synopsis target-domain
Hwi_Handle Hwi_create(Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
 
Void Hwi_construct(Hwi_Struct *structP, Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
intNum — interrupt number
hwiFxn — pointer to ISR 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
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 following properties are specified by a structure of type Hwi_Params.
  • 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.
  • The maskSetting element defines the dispatcherAutoNestingSupport behavior of the interrupt.
Hwi_create returns a pointer to the created Hwi object.
Instance Deletion

C synopsis target-domain
Void Hwi_delete(Hwi_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
 
Void Hwi_destruct(Hwi_Struct *structP);
// Finalize the instance object inside the provided structure
 
Hwi_getFunc()  // instance

Get Hwi function and arg

C synopsis target-domain
IHwi_FuncPtr Hwi_getFunc(Hwi_Handle handle, UArg *arg);
 
ARGUMENTS
handle — handle of a previously-created Hwi instance object
arg — pointer for returning hwi's ISR function argument
RETURNS
hwi's ISR function
 
Hwi_getHookContext()  // instance

Get hook instance's context for a Hwi

C synopsis target-domain
Ptr Hwi_getHookContext(Hwi_Handle handle, Int id);
 
ARGUMENTS
handle — handle of a previously-created Hwi instance object
RETURNS
hook instance's context for hwi
 
Hwi_getIrp()  // instance

Get address of interrupted instruction

C synopsis target-domain
IHwi_Irp Hwi_getIrp(Hwi_Handle handle);
 
ARGUMENTS
handle — handle of a previously-created Hwi instance object
RETURNS
most current IRP of a Hwi
 
Hwi_reconfig()  // instance

Reconfigure a dispatched interrupt

C synopsis target-domain
Void Hwi_reconfig(Hwi_Handle handle, Hwi_FuncPtr fxn, Hwi_Params *params);
 
ARGUMENTS
handle — handle of a previously-created Hwi instance object
 
Hwi_setFunc()  // instance

Overwrite Hwi function and arg

C synopsis target-domain
Void Hwi_setFunc(Hwi_Handle handle, IHwi_FuncPtr fxn, UArg arg);
 
ARGUMENTS
handle — handle of a previously-created Hwi instance object
fxn — pointer to ISR function
arg — argument to ISR function
DETAILS
Replaces a Hwi object's hwiFxn function originally provided in create.
 
Hwi_setHookContext()  // instance

Set hook instance's context for a Hwi

C synopsis target-domain
Void Hwi_setHookContext(Hwi_Handle handle, Int id, Ptr hookContext);
 
ARGUMENTS
handle — handle of a previously-created Hwi instance object
id — hook instance's ID
hookContext — value to write to context
Instance Convertors

C synopsis target-domain
IHwi_Handle Hwi_Handle_upCast(Hwi_Handle handle);
// unconditionally move one level up the inheritance hierarchy
 
Hwi_Handle Hwi_Handle_downCast(IHwi_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins

C synopsis target-domain
Int Hwi_Object_count();
// The number of statically-created instance objects
 
Hwi_Handle Hwi_Object_get(Hwi_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
 
Hwi_Handle Hwi_Object_first();
// The handle of the first dynamically-created instance object, or NULL
 
Hwi_Handle Hwi_Object_next(Hwi_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
 
IHeap_Handle Hwi_Object_heap();
// The heap used to allocate dynamically-created instance objects
 
Types_Label *Hwi_Handle_label(Hwi_Handle handle, Types_Label *buf);
// The label associated with this instance object
 
String Hwi_Handle_name(Hwi_Handle handle);
// The name of this instance object
 
Configuration settings sourced in ti/sysbios/family/arm/m3/Hwi.xdc
var Hwi = xdc.useModule('ti.sysbios.family.arm.m3.Hwi');
module-wide constants & types
        const Hwi.MaskingOption_NONE;
        const Hwi.MaskingOption_ALL;
        const Hwi.MaskingOption_SELF;
        const Hwi.MaskingOption_BITMASK;
        const Hwi.MaskingOption_LOWER;
 
        obj.STKALIGN// Auto stack alignment in exception = Bits8  ...
        obj.BFHFNMIGN// All faults ignore BUS Faults = Bits8  ...
        obj.DIV_0_TRP// Trap on divide by zero = Bits8  ...
        obj.UNALIGN_TRP// Trap on all unaligned accesses = Bits8  ...
        obj.USERSETMPEND// Allow user to trigger interrupts = Bits8  ...
        obj.NONEBASETHRDENA// Allow entering thread mode anytime = Bits8  ...
 
        obj.threadType = BIOS.ThreadType  ...
        obj.threadHandle = Ptr  ...
        obj.threadStack = Ptr  ...
        obj.threadStackSize = SizeT  ...
        obj.r0 = Ptr  ...
        obj.r1 = Ptr  ...
        obj.r2 = Ptr  ...
        obj.r3 = Ptr  ...
        obj.r4 = Ptr  ...
        obj.r5 = Ptr  ...
        obj.r6 = Ptr  ...
        obj.r7 = Ptr  ...
        obj.r8 = Ptr  ...
        obj.r9 = Ptr  ...
        obj.r10 = Ptr  ...
        obj.r11 = Ptr  ...
        obj.r12 = Ptr  ...
        obj.sp = Ptr  ...
        obj.lr = Ptr  ...
        obj.pc = Ptr  ...
        obj.psr = Ptr  ...
        obj.ICSR = Ptr  ...
        obj.MMFSR = Ptr  ...
        obj.BFSR = Ptr  ...
        obj.UFSR = Ptr  ...
        obj.HFSR = Ptr  ...
        obj.DFSR = Ptr  ...
        obj.MMAR = Ptr  ...
        obj.BFAR = Ptr  ...
        obj.AFSR = Ptr  ...
 
        obj.registerFxn = Void(*)(Int)  ...
        obj.createFxn = Void(*)(IHwi.Handle,Error.Block*)  ...
        obj.beginFxn = Void(*)(IHwi.Handle)  ...
        obj.endFxn = Void(*)(IHwi.Handle)  ...
        obj.deleteFxn = Void(*)(IHwi.Handle)  ...
 
        obj.hwiStackPeak = SizeT  ...
        obj.hwiStackSize = SizeT  ...
        obj.hwiStackBase = Ptr  ...
module-wide config parameters
        msg: "A_unsupportedMaskingOption: unsupported maskSetting."
    };
        msg: "E_NMI: %s"
    };
        msg: "E_alreadyDefined: Hwi already defined: intr# %d"
    };
        msg: "E_busFault: %s, address: %08x"
    };
        msg: "E_debugMon: %s"
    };
        msg: "E_exception: id = %d, pc = %08x.\nTo see more exception detail, set ti.sysbios.family.arm.m3.Hwi.enableException = true or,\nexamine the Exception view for the ti.sysbios.family.arm.m3.Hwi module using ROV."
    };
        msg: "E_hardFault: %s"
    };
        msg: "E_hwiLimitExceeded: Too many interrupts defined"
    };
        msg: "E_memFault: %s, address: %08x"
    };
        msg: "E_noIsr: id = %d, pc = %08x"
    };
        msg: "E_reserved: %s %d"
    };
        msg: "E_svCall: svNum = %d"
    };
        msg: "E_usageFault: %s"
    };
        mask: Diags.USER2,
        msg: "LD_end: hwi: 0x%x"
    };
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
    };
 
    Hwi.excContextBuffers//  = Ptr[] undefined;
    Hwi.excStackBuffers//  = Ptr[] undefined;
    Hwi.intAffinity//  = UInt8[] undefined;
        STKALIGN: 1,
        BFHFNMIGN: 0,
        DIV_0_TRP: 0,
        UNALIGN_TRP: 0,
        USERSETMPEND: 0,
        NONEBASETHRDENA: 0
    };
    Hwi.resetFunc// Reset Handler. Default is c_int00 = Void(*)(Void) undefined;
module-wide functions
per-instance config parameters
    var params = new Hwi.Params// Instance config-params object;
        params.arg// ISR function argument. Default is 0 = UArg 0;
per-instance creation
    var inst = Hwi.create// Create an instance-object(Int intNum, Void(*)(UArg) hwiFxn, params);
 
 
enum Hwi.MaskingOption

Shorthand interrupt masking options

Configuration settings
values of type Hwi.MaskingOption
    const Hwi.MaskingOption_NONE;
    const Hwi.MaskingOption_ALL;
    const Hwi.MaskingOption_SELF;
    const Hwi.MaskingOption_BITMASK;
    const Hwi.MaskingOption_LOWER;
 
VALUES
MaskingOption_NONE — No interrupts are disabled
MaskingOption_ALL — All interrupts are disabled
MaskingOption_SELF — Only this interrupt is disabled
MaskingOption_BITMASK — User supplies interrupt enable 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.
C SYNOPSIS
 
struct Hwi.CCR

NVIC Configuration Control Register (CCR)

Configuration settings
var obj = new Hwi.CCR;
 
    obj.STKALIGN = Bits8  ...
    // Auto stack alignment in exception
    obj.BFHFNMIGN = Bits8  ...
    // All faults ignore BUS Faults
    obj.DIV_0_TRP = Bits8  ...
    // Trap on divide by zero
    obj.UNALIGN_TRP = Bits8  ...
    // Trap on all unaligned accesses
    obj.USERSETMPEND = Bits8  ...
    // Allow user to trigger interrupts
    obj.NONEBASETHRDENA = Bits8  ...
    // Allow entering thread mode anytime
 
C SYNOPSIS
 
struct Hwi.ExcContext

Exception Context - Register contents at the time of an exception

Configuration settings
var obj = new Hwi.ExcContext;
 
    obj.threadType = BIOS.ThreadType  ...
    obj.threadHandle = Ptr  ...
    obj.threadStack = Ptr  ...
    obj.threadStackSize = SizeT  ...
    obj.r0 = Ptr  ...
    obj.r1 = Ptr  ...
    obj.r2 = Ptr  ...
    obj.r3 = Ptr  ...
    obj.r4 = Ptr  ...
    obj.r5 = Ptr  ...
    obj.r6 = Ptr  ...
    obj.r7 = Ptr  ...
    obj.r8 = Ptr  ...
    obj.r9 = Ptr  ...
    obj.r10 = Ptr  ...
    obj.r11 = Ptr  ...
    obj.r12 = Ptr  ...
    obj.sp = Ptr  ...
    obj.lr = Ptr  ...
    obj.pc = Ptr  ...
    obj.psr = Ptr  ...
    obj.ICSR = Ptr  ...
    obj.MMFSR = Ptr  ...
    obj.BFSR = Ptr  ...
    obj.UFSR = Ptr  ...
    obj.HFSR = Ptr  ...
    obj.DFSR = Ptr  ...
    obj.MMAR = Ptr  ...
    obj.BFAR = Ptr  ...
    obj.AFSR = Ptr  ...
 
C SYNOPSIS
 
struct Hwi.HookSet

Hwi hook set type definition

Configuration settings
var obj = new Hwi.HookSet;
 
    obj.registerFxn = Void(*)(Int)  ...
    obj.createFxn = Void(*)(IHwi.Handle,Error.Block*)  ...
    obj.beginFxn = Void(*)(IHwi.Handle)  ...
    obj.endFxn = Void(*)(IHwi.Handle)  ...
    obj.deleteFxn = Void(*)(IHwi.Handle)  ...
 
DETAILS
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.
C SYNOPSIS
 
struct Hwi.StackInfo

Structure contains Hwi stack usage info

Configuration settings
var obj = new Hwi.StackInfo;
 
    obj.hwiStackPeak = SizeT  ...
    obj.hwiStackSize = SizeT  ...
    obj.hwiStackBase = Ptr  ...
 
DETAILS
Used by getStackInfo() and viewGetStackInfo() functions
C SYNOPSIS
 
config Hwi.A_unsupportedMaskingOption  // module-wide

Assert when bad maskSetting parameter provided

Configuration settings
Hwi.A_unsupportedMaskingOption = Assert.Desc {
    msg: "A_unsupportedMaskingOption: unsupported maskSetting."
};
 
C SYNOPSIS
 
config Hwi.E_NMI  // module-wide

Error raised when NMI exception occurs

Configuration settings
Hwi.E_NMI = Error.Desc {
    msg: "E_NMI: %s"
};
 
C SYNOPSIS
 
config Hwi.E_alreadyDefined  // module-wide

Error raised when Hwi is already defined

Configuration settings
Hwi.E_alreadyDefined = Error.Desc {
    msg: "E_alreadyDefined: Hwi already defined: intr# %d"
};
 
C SYNOPSIS
 
config Hwi.E_busFault  // module-wide

Error raised when bus fault exception occurs

Configuration settings
Hwi.E_busFault = Error.Desc {
    msg: "E_busFault: %s, address: %08x"
};
 
C SYNOPSIS
 
config Hwi.E_debugMon  // module-wide

Error raised when debugMon exception occurs

Configuration settings
Hwi.E_debugMon = Error.Desc {
    msg: "E_debugMon: %s"
};
 
C SYNOPSIS
 
config Hwi.E_exception  // module-wide

Error raised when an exception occurs

Configuration settings
Hwi.E_exception = Error.Desc {
    msg: "E_exception: id = %d, pc = %08x.\nTo see more exception detail, set ti.sysbios.family.arm.m3.Hwi.enableException = true or,\nexamine the Exception view for the ti.sysbios.family.arm.m3.Hwi module using ROV."
};
 
C SYNOPSIS
 
config Hwi.E_hardFault  // module-wide

Error raised when hard fault exception occurs

Configuration settings
Hwi.E_hardFault = Error.Desc {
    msg: "E_hardFault: %s"
};
 
C SYNOPSIS
 
config Hwi.E_hwiLimitExceeded  // module-wide

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

Configuration settings
Hwi.E_hwiLimitExceeded = Error.Desc {
    msg: "E_hwiLimitExceeded: Too many interrupts defined"
};
 
C SYNOPSIS
 
config Hwi.E_memFault  // module-wide

Error raised when memory fault exception occurs

Configuration settings
Hwi.E_memFault = Error.Desc {
    msg: "E_memFault: %s, address: %08x"
};
 
C SYNOPSIS
 
config Hwi.E_noIsr  // module-wide

Error raised when an uninitialized interrupt occurs

Configuration settings
Hwi.E_noIsr = Error.Desc {
    msg: "E_noIsr: id = %d, pc = %08x"
};
 
C SYNOPSIS
 
config Hwi.E_reserved  // module-wide

Error raised when reserved exception occurs

Configuration settings
Hwi.E_reserved = Error.Desc {
    msg: "E_reserved: %s %d"
};
 
C SYNOPSIS
 
config Hwi.E_svCall  // module-wide

Error raised when svCall exception occurs

Configuration settings
Hwi.E_svCall = Error.Desc {
    msg: "E_svCall: svNum = %d"
};
 
C SYNOPSIS
 
config Hwi.E_usageFault  // module-wide

Error raised when usage fault exception occurs

Configuration settings
Hwi.E_usageFault = Error.Desc {
    msg: "E_usageFault: %s"
};
 
C SYNOPSIS
 
config Hwi.LD_end  // module-wide

Issued just after return from Hwi function (with interrupts disabled)

Configuration settings
Hwi.LD_end = Log.EventDesc {
    mask: Diags.USER2,
    msg: "LD_end: hwi: 0x%x"
};
 
C SYNOPSIS
 
config Hwi.LM_begin  // module-wide

Issued just prior to Hwi function invocation (with interrupts disabled)

Configuration settings
Hwi.LM_begin = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
};
 
C SYNOPSIS
 
config Hwi.NUM_INTERRUPTS  // module-wide

The Cortex M3 NVIC supports up to 256 interrupts/exceptions

Configuration settings
Hwi.NUM_INTERRUPTS = Int undefined;
 
DETAILS
The actual number supported is device specific and provided by the catalog device specification.
C SYNOPSIS
 
config Hwi.NUM_PRIORITIES  // module-wide

The Cortex M3 NVIC supports up to 256 interrupt priorities

Configuration settings
Hwi.NUM_PRIORITIES = Int undefined;
 
DETAILS
The actual number supported is device specific and provided by the catalog device specification.
C SYNOPSIS
 
config Hwi.disablePriority  // module-wide

The priority that BASEPRI is set to by Hwi_disable()

Configuration settings
Hwi.disablePriority = UInt undefined;
 
DETAILS
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().
C SYNOPSIS
 
config Hwi.dispatcherAutoNestingSupport  // module-wide

Include interrupt nesting logic in interrupt dispatcher?

Configuration settings
Hwi.dispatcherAutoNestingSupport = Bool true;
 
DETAILS
Default is true.
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.
C SYNOPSIS
 
config Hwi.dispatcherIrpTrackingSupport  // module-wide

Controls whether the dispatcher retains the interrupted thread's return address

Configuration settings
Hwi.dispatcherIrpTrackingSupport = Bool true;
 
DETAILS
This option is enabled by default.
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.
C SYNOPSIS
 
config Hwi.dispatcherSwiSupport  // module-wide

Include Swi scheduling logic in interrupt dispatcher?

Configuration settings
Hwi.dispatcherSwiSupport = Bool undefined;
 
DETAILS
Default is inherited from BIOS.swiEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that Swis will not be posted from any of their Hwi threads.
WARNING
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Swi scheduler prior to returning from an interrupt. With this setting, Swis MUST NOT be posted from Hwi functions!
C SYNOPSIS
 
config Hwi.dispatcherTaskSupport  // module-wide

Include Task scheduling logic in interrupt dispatcher?

Configuration settings
Hwi.dispatcherTaskSupport = Bool undefined;
 
DETAILS
Default is inherited from BIOS.taskEnabled, which is true by default.
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.
C SYNOPSIS
 
config Hwi.excHandlerFunc  // module-wide

Exception handler function pointer

Configuration settings
Hwi.excHandlerFunc = Void(*)(UInt*,UInt) Hwi.excHandlerMax;
 
DETAILS
The default is determined by the value of Hwi.enableException.
If the user does NOT set this parameter, then the following default behavior is followed:
If Hwi.enableException is true, then the internal 'Hwi_excHandlerMax' function is used. This exception handler saves the exception context then does a complete exception decode and dump to the console, then raises an Error. The exception context can be viewed within CCS in the ROV Hwi module's Exception view.
If Hwi.enableException is false, then the internal 'Hwi_excHandlerMin' function is used. This exception handler saves the exception context then raises an Error. The exception context can be viewed within CCS in the ROV Hwi module's Exception view.
If the user sets this parameter to their own function, then the user's function will be invoked with the following arguments:
Void myExceptionHandler(UInt *excStack, UInt lr);
Where 'excStack' is the address of the stack containing the register context at the time of the exception, and 'lr' is the link register value when the low-level-assembly-coded exception handler was vectored to.
If this parameter is set to 'null', then an infinite while loop is entered when an exception occurs. This setting minimizes code and data footprint but provides no automatic exception decoding.
C SYNOPSIS
 
config Hwi.excHookFunc  // module-wide

User Exception hook function

Configuration settings
Hwi.excHookFunc = Void(*)(Hwi.ExcContext*) null;
 
DETAILS
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).
C SYNOPSIS
 
config Hwi.excHookFuncs  // module-wide
Configuration settings
Hwi.excHookFuncs = Hwi.ExceptionHookFuncPtr[] undefined;
 
C SYNOPSIS
 
config Hwi.nullIsrFunc  // module-wide

Uninitialized ISR Handler. Default is set to an internal exception handler

Configuration settings
Hwi.nullIsrFunc = Void(*)(Void) undefined;
 
C SYNOPSIS
 
config Hwi.priGroup  // module-wide

The PRIGROUP setting. Default is 0

Configuration settings
Hwi.priGroup = UInt 0;
 
DETAILS
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.
C SYNOPSIS
 
metaonly config Hwi.busFaultFunc  // module-wide

Bus Fault Handler. Default is set to an internal exception handler

Configuration settings
Hwi.busFaultFunc = Void(*)(Void) undefined;
 
 
metaonly config Hwi.common$  // module-wide

Common module configuration parameters

Configuration settings
Hwi.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 config Hwi.debugMonFunc  // module-wide

Debug Mon Handler. Default is set to an internal exception handler

Configuration settings
Hwi.debugMonFunc = Void(*)(Void) undefined;
 
 
metaonly config Hwi.dispatchTableSize  // module-wide

Size (in number of interrupts) of the table used by the interrupt dispatcher to locate the corresponding Hwi object. By default, Hwi.dispatchTableSize will be internally set to the number of interrupts supported by the device

Configuration settings
Hwi.dispatchTableSize = UInt undefined;
 
DETAILS
When the Hwi dispatch table size is equal to the number of interrupts supported NUM_INTERRUPTS by the device, a linear-indexed dispatch table mechanism is used that will consume 4 bytes of RAM for each interrupt supported.
If the dispatch table size is set to a number less than the number of interrupts supported by the device, then a non linear-indexed dispatch table mechanism is employed that uses 12 bytes of RAM for each interrupt supported.
Consequently, for applications that use less than 1/3 of the total number of interrupts supported by the device, setting this parameter to the number of interrupts ACTUALLY USED will result in less RAM memory being used than otherwise.
For applications that use very few interrupts, this can be a significant RAM memory savings.</p>
 
metaonly config Hwi.enableException  // module-wide

Enable full exception decoding

Configuration settings
Hwi.enableException = Bool true;
 
DETAILS
When this is enabled, the exception handler will fully decode an exception and dump the registers to the system console.
 
metaonly config Hwi.excContextBuffer  // module-wide

User Exception Context Buffer Address

Configuration settings
Hwi.excContextBuffer = Ptr undefined;
 
DETAILS
By default, when an exception occurs, an ExcContext structure is allocated on the ISR stack and filled in within the exception handler.
If excContextBuffer is initialized by the user, the ExcContext structure will be placed at that address instead.
The buffer must be large enough to contain an ExcContext structure.
 
metaonly config Hwi.excContextBuffers  // module-wide
Configuration settings
Hwi.excContextBuffers = Ptr[] undefined;
 
 
metaonly config Hwi.excStackBuffer  // module-wide

User Exception Stack Buffer Address

Configuration settings
Hwi.excStackBuffer = Ptr undefined;
 
DETAILS
By default, when an exception occurs, a pointer to the base address of the stack being used by the thread causing the exception is placed
If excStackBuffer is initialized by the user, the stack contents of the thread causing the exception will be copied to that address instead.
The buffer must be large enough to contain the largest task stack or ISR stack defined in the application.
 
metaonly config Hwi.excStackBuffers  // module-wide
Configuration settings
Hwi.excStackBuffers = Ptr[] undefined;
 
 
metaonly config Hwi.hardFaultFunc  // module-wide

Hard Fault Handler. Default is set to an internal exception handler

Configuration settings
Hwi.hardFaultFunc = Void(*)(Void) undefined;
 
 
metaonly config Hwi.intAffinity  // module-wide
Configuration settings
Hwi.intAffinity = UInt8[] undefined;
 
 
metaonly config Hwi.memFaultFunc  // module-wide

Hard Mem Handler. Default is set to an internal exception handler

Configuration settings
Hwi.memFaultFunc = Void(*)(Void) undefined;
 
 
metaonly config Hwi.nmiFunc  // module-wide

NMI Handler. Default is set to an internal exception handler

Configuration settings
Hwi.nmiFunc = Void(*)(Void) undefined;
 
 
metaonly config Hwi.nvicCCR  // module-wide

NVIC CCR register settings

Configuration settings
Hwi.nvicCCR = Hwi.CCR {
    STKALIGN: 1,
    BFHFNMIGN: 0,
    DIV_0_TRP: 0,
    UNALIGN_TRP: 0,
    USERSETMPEND: 0,
    NONEBASETHRDENA: 0
};
 
DETAILS
These setting are written to Hwi_nvic.CCR at startup time.
See the Cortex M3 architecture reference manual for details on the meanings of these parameters.
 
metaonly config Hwi.reservedFunc  // module-wide

Reserved Exception Handler. Default is set to an internal exception handler

Configuration settings
Hwi.reservedFunc = Void(*)(Void) undefined;
 
 
metaonly config Hwi.resetFunc  // module-wide

Reset Handler. Default is c_int00

Configuration settings
Hwi.resetFunc = Void(*)(Void) undefined;
 
 
metaonly config Hwi.resetVectorAddress  // module-wide

Reset vector table address. Default is 0x00000000

Configuration settings
Hwi.resetVectorAddress = Ptr 0x00000000;
 
DETAILS
This parameter is the address of the vector table used at system reset time. Typically this is placed at 0x00000000.
If the Hwi.resetVectorAddress has a different value than the Hwi.vectorTableAddress then two vector tables are generated, one at the Hwi.resetVectorAddress and another at the Hwi.vectorTableAddress.
After the initial boot code has been executed at startup, the NVIC's Vector Table Offset Register will be programmed to point to the vector table at the Hwi.vectorTableAddress.
is created and placed in the ".resetVecs" section.
 
metaonly config Hwi.svCallFunc  // module-wide

SVCall Handler. Default is set to an internal exception handler

Configuration settings
Hwi.svCallFunc = Void(*)(Void) undefined;
 
 
metaonly config Hwi.usageFaultFunc  // module-wide

Usage Fault Handler. Default is set to an internal exception handler

Configuration settings
Hwi.usageFaultFunc = Void(*)(Void) undefined;
 
 
metaonly config Hwi.vectorTableAddress  // module-wide

Location of the Runtime Interrupt Vector Table. Default is device dependent

Configuration settings
Hwi.vectorTableAddress = Ptr 0x00000000;
 
DETAILS
This parameter allows the user to override the default placement of the runtime interrupt vector table. The NVIC's Vector Table Offset Register (VTOR) is also programmed to this value.
Some systems require the runtime vector table to be placed at an address other than 0 but still need a copy of the two M3 boot vectors (SP and reset PC), located there. To achieve this, a separate parameter resetVectorAdress is provided. If the resetVectorAddress has a different value then the vectorTableAddress then a separate vector table is generated and placed at that address.
The vector table must be placed at an address at or lower than 0x3FFFFC00 and must be aligned on an even 64 word boundary.
 
metaonly Hwi.addHookSet()  // module-wide

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

Configuration settings
Hwi.addHookSet(IHwi.HookSet hook) returns Void
 
ARGUMENTS
hook — structure of type HookSet
DETAILS
HookSet structure elements may be omitted, in which case those elements will not exist.
Instance Config Parameters

Configuration settings
var params = new Hwi.Params;
// Instance config-params object
    params.arg = UArg 0;
    // ISR function argument. Default is 0
    params.enableInt = Bool true;
    // Enable this interrupt when object is created? Default is true
    params.eventId = Int -1;
    // Interrupt event ID (Interrupt Selection Number)
    params.maskSetting = IHwi.MaskingOption IHwi.MaskingOption_LOWER;
    // Interrupt Masking Option. Only MaskingOption_LOWER is supported
    params.priority = Int 255;
    // Interrupt priority. The default is 255 which is the lowest priority
    params.useDispatcher = Bool true;
    // Use the interrupt dispatcher with this interrupt. Default is true
 
config Hwi.Params.arg  // instance

ISR function argument. Default is 0

Configuration settings
var params = new Hwi.Params;
  ...
params.arg = UArg 0;
 
C SYNOPSIS
 
config Hwi.Params.enableInt  // instance

Enable this interrupt when object is created? Default is true

Configuration settings
var params = new Hwi.Params;
  ...
params.enableInt = Bool true;
 
C SYNOPSIS
 
config Hwi.Params.eventId  // instance

Interrupt event ID (Interrupt Selection Number)

Configuration settings
var params = new Hwi.Params;
  ...
params.eventId = Int -1;
 
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
C SYNOPSIS
 
config Hwi.Params.maskSetting  // instance

Interrupt Masking Option. Only MaskingOption_LOWER is supported

Configuration settings
var params = new Hwi.Params;
  ...
 
DETAILS
The NVIC interrupt controller is designed for priority based interrupts. No support is provided for anything but Hwi.MaskingOption_LOWER.
C SYNOPSIS
 
config Hwi.Params.priority  // instance

Interrupt priority. The default is 255 which is the lowest priority

Configuration settings
var params = new Hwi.Params;
  ...
params.priority = Int 255;
 
DETAILS
The default value of -1 is used as a flag to indicate the lowest (logical) device-specific priority value.
Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
Priority 0 is the highest priority and by default is reserved for zero latency interrupts (see disablePriority).
Valid priorities values are device dependent and their nesting behaviors depend on the priGroup setting.
See the Cortex M3 architecture reference manual for details on the meanings of these parameters.
C SYNOPSIS
 
config Hwi.Params.useDispatcher  // instance

Use the interrupt dispatcher with this interrupt. Default is true

Configuration settings
var params = new Hwi.Params;
  ...
params.useDispatcher = Bool true;
 
DETAILS
If set to false, the interrupt dispatcher is NOT used. Instead, the configured Hwi function address is placed directly in the vector table, which results in the dispatcher being bypassed.
WARNING
Interrupts configured to bupass the dispatcher are not allowed to call ANY SYS/BIOS APIs that effect thread scheduling. Examples of API that should no be invoked are:
Swi_post(),
Semaphore_post(),
Event_post(),
Task_yield()
Additionally, although the signature for a non-dispatched interrupt function is the same as that for a dispatched interrupt (see FuncPtr), no argument is actually passed to the non-dispatched ISR handler.
C SYNOPSIS
Static Instance Creation

Configuration settings
var params = new Hwi.Params;
// Allocate instance config-params
params.config =   ...
// Assign individual configs
 
var inst = Hwi.create(Int intNum, Void(*)(UArg) hwiFxn, params);
// Create an instance-object
ARGUMENTS
intNum — interrupt number
hwiFxn — pointer to ISR 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
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 following properties are specified by a structure of type Hwi_Params.
  • 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.
  • The maskSetting element defines the dispatcherAutoNestingSupport behavior of the interrupt.
Hwi_create returns a pointer to the created Hwi object.
generated on Tue, 14 Feb 2017 19:59:19 GMT