module ti.sysbios.family.c28.Hwi

C28x Hardware Interrupt Manager

This Hwi module provides C28 family-specific implementations of the APIs defined in IHwi. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/c28/Hwi.xdc
#include <ti/sysbios/family/c28/Hwi.h>
Functions
Void
Void
Void
Bits16 
Bits16 
Bits16 
Bits16 
Void
Void 
Void 
Bits16 
Bits16 
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
Defines
#define
Typedefs
typedef Void 
typedef Hwi_Object *
typedef struct
typedef UArg 
typedef enum
typedef struct
typedef struct
typedef Void 
typedef struct
typedef struct
Constants
extern const Assert_Id 
extern const Assert_Id 
extern const Assert_Id 
extern const Bool 
extern const Bool 
extern const Bool 
extern const Bool 
extern const Error_Id 
extern const Error_Id 
extern const Log_Event 
extern const Log_Event 
extern const Int 
extern const Int 
extern const Bits16 
 
DETAILS
This Hwi module provides C28 family-specific implementations of the APIs defined in IHwi.
Additional C28 device-specific APIs are also provided.
ISRs specified with Hwi_plug will not go through the dispatcher; the ISR function will be directly plugged into the vector table. Hwi_plug can be used for any ISR which does not call any SYS/BIOS APIs.
ISRs can be plugged or created statically in the configuration script or dynamically at runtime.

PIE interrupts

The peripheral interrupt expansion (PIE) block multiplexes 96 interrupts into 12 CPU interrupts. The PIE vector table includes entries for each of these 96 interrupts. The relationship between the numbers corresponding to PIE interrupts and their groups (CPU interrupt) is as follows: PIEGROUPNUM = [(PIENUM - 32) / 8] + 1

PIE MUXed Peripheral Interrupt Vector Table

The table below shows a mapping between the PIENUM (interrupt id) and the various PIE groups. INTX.Y represents the interrupt number for the PIE interrupt belonging to group X and group-specific id Y.

INTX.1INTX.2INTX.3INTX.4INTX.5INTX.6INTX.7INTX.8
INT1.Y3233343536373839
INT2.Y4041424344454647
INT3.Y4849505152535455
INT4.Y5657585960616263
INT5.Y6465666768697071
INT6.Y7273747576777879
INT7.Y8081828384858687
INT8.Y8889909192939495
INT9.Y96979899100101102103
INT10.Y104105106107108109110111
INT11.Y112113114115116117118119
INT12.Y120121122123124125126127

On F2837X devices, there is an enhanced PIE block that can support up to 192 individual interrupts multiplexed into the 12 CPU interrupts. The mapping between the PIENUM and PIE groups is identical to that shown in the above table for the first 96 interrupts. For the next 96 interrupts, the mapping is shown in the below table.

ePIE MUXed Peripheral Interrupt Vector Table

The table below shows a mapping between the PIENUM (interrupt id) and the various PIE groups for ePIE interrupts 128 to 223. INTX.Y represents the interrupt number for the PIE interrupt belonging to group X and group-specific id Y.

INTX.1INTX.2INTX.3INTX.4INTX.5INTX.6INTX.7INTX.8
INT1.Y128129130131132133134135
INT2.Y136137138139140141142143
INT3.Y144145146147148149150151
INT4.Y152153154155156157158159
INT5.Y160161162163164165166167
INT6.Y168169170171172173174175
INT7.Y176177178179180181182183
INT8.Y184185186187188189190191
INT9.Y192193194195196197198199
INT10.Y200201202203204205206207
INT11.Y208209210211212213214215
INT12.Y216217218219220221222223

PIE interrupts must clear the CPU acknowledge bit for their respective PIE block before further interrupts from that block can occur. The SYS/BIOS 6 dispatcher (used by interrupts created using create) takes care of this, however this differs from DSP/BIOS 5, in which the application is expected to acknowledge the interrupt.
PIE interrupt ISRs plugged with plug(which do not use the dispatcher), as well as legacy created PIE HWI instances, must acknowledge the interrupt manually before returning from the ISR.
EXAMPLE
The following configuration code can be used to plug the function 'myHwi' into the vector table for PIE group 5, interrupt 1. Using the above table, one can see that this corresponds to interrupt ID 64:
      Program.global.hwi5 = Hwi.create(64, '&myHwi');
MINIMAL LATENCY INTERRUPTS
For applications requiring extremely low interrupt latency, the 28x Hwi module allows the user to configure interrupts that operate independent of the SYS/BIOS interrupt dispatcher which are disabled for extremely short periods of time as compared to interrupts handled by the dispatcher.
Though not a precisely correct classification, these interrupts are referred to as "Zero Latency" interrupts.
When configured to support "Zero Latency" interrupts, the disable, restore, and enable APIs manipulate the IER register rather than the INTM bit to provide critical section protection. The IER bits associated with the configured "Zero Latency" interrupts are left enabled while all other bits are disabled and enabled as required to functionally achieve the API requirements. Explicit calls to the disableIER or disablePIEIER APIs operate on ALL IER bits, even those associated with the configured "Zero Latency" interrupts. Refer to zeroLatencyIERMask for using information.
NOTE
In this Hwi module implementation, the instance config parameter value MaskingOption_LOWER is equivalent to MaskingOption_SELF. Statically configuring a Hwi object's Params.maskSetting to MaskingOption_LOWER will result in the generation of a benign build warning. Dynamic usages of MaskingOption_LOWER will be silently converted to MaskingOption_SELF.

Calling Context

Function Hwi Swi Task Main Startup
clearInterrupt Y Y Y Y N
disable Y Y Y Y Y
disableIER Y Y Y Y Y
disableInterrupt Y Y Y Y N
disablePIEIER Y Y Y Y N
enable Y Y Y N N
enableIER Y Y Y Y Y
enableInterrupt Y Y Y Y N
enablePIEIER Y Y Y Y N
getHandle Y Y Y Y N
getIFR Y Y Y Y Y
getIntrReturnAddr Y Y Y Y Y
Params_init Y Y Y Y N
pieEnabled Y Y Y Y Y
plug Y Y Y Y Y
restore Y Y Y Y Y
restoreIER Y Y Y Y Y
restoreInterrupt Y Y Y Y Y
ack Y Y Y Y Y
create N N Y Y N
construct N N Y Y N
delete N N Y Y N
destruct N N Y Y N
getHookContext Y Y Y Y N
reconfig 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).
 
const Hwi_NUM_INTERRUPTS

C28 supports 32 interrupts

C synopsis target-domain
#define Hwi_NUM_INTERRUPTS (Int)32
 
 
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_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_PlugFuncPtr

Hwi plug function type definition, which doesn't take an arg

C synopsis target-domain
typedef Void (*Hwi_PlugFuncPtr)(Void);
 
 
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_badIntNum  // module-wide

Assert raised when an invalid interrupt number is passed to a Hwi call

C synopsis target-domain
extern const Assert_Id Hwi_A_badIntNum;
 
 
config Hwi_A_invalidArg  // module-wide

Assert raised when an invalid argument has been passed to a function

C synopsis target-domain
extern const Assert_Id Hwi_A_invalidArg;
 
 
config Hwi_A_zeroLatencyConflict  // module-wide

Assert raised when there is a conflict with the zero latency IER mask

C synopsis target-domain
extern const Assert_Id Hwi_A_zeroLatencyConflict;
 
DETAILS
This assert is raised when trying to create a Hwi with an intNum that conflicts with the supplied zero latency IER mask.
 
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_unpluggedInterrupt  // module-wide

Error raised when an unplugged interrupt is flagged

C synopsis target-domain
extern const Error_Id Hwi_E_unpluggedInterrupt;
 
 
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_ALL  // module-wide
C synopsis target-domain
extern const Int Hwi_NUM_INTERRUPTS_ALL;
 
 
config Hwi_NUM_INTERRUPTS_PIE  // module-wide

C28 supports 96 PIE interrupts

C synopsis target-domain
extern const Int Hwi_NUM_INTERRUPTS_PIE;
 
DETAILS
Note: TMS320F2837X devices have an enhanced PIE that supports 196 PIE interrupts. This config param is set to 192 by default.
 
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_zeroLatencyIERMask  // module-wide

Zero Latency IER Mask

C synopsis target-domain
extern const Bits16 Hwi_zeroLatencyIERMask;
 
DETAILS
CPU interrupts specified in this mask (which corresponds to the 16-bit IER register) are carefully managed so that they are disabled for only the bare minimum time required to safely manipulated the IER register. This means that the disable, enable, and restore calls leave the zero latency CPU interrupts enabled after being called. Zero latency operation may be used to ensure minimal interrupt-to-ISR time for non-BIOS interrupt handlers in applications that demand low latency.
NOTE
While referred to as "Zero Latency Interrupts", the interrupts specified in the zeroLatencyIERMask are NOT TRULY ZERO LATENCY! They are still disabled briefly in software by the Hwi_disable(), Hwi_restore(), and Hwi_enable() APIs while the IER register bits are manipulated. Additionally, interrupts are globally disabled automatically by the 28x hardware when an interrupt is taken. The Hwi module's interrupt dispatcher quickly (ie: within 30 instructions) re-enables interrupts globally after carefully manipulating the IER register accordingly.
It is important to note that zero latency and non-zero latency PIE interrupts may not share a common PIE group. The entire PIE group whose bit is set in the zeroLatencyIERMask will be treated as zero latency.
WARNING
Enabling zero latency mode (specifying a non-zero zeroLatencyIERMask) generates alternate (and slower) code used to disable, enable and restore interrupts. This alternate code will maintain a shadow copy of interrupt state (IER register and global interrupt state). disableIER, enableIER and restoreIER will update both the IER register and its shadow. The disable call will copy the zero latency IER mask (supplied here) into the IER register. The enable call will copy the contents of the shadow IER register into the actual register. The restore call may either disable or enable the non-zero-latency interrupts.
It is important to be aware of the performance penalty associated with using zero latency interrupts before using this feature.
Example:
  var Hwi = xdc.useModule('ti.sysbios.family.c28.Hwi');
  Hwi.zeroLatencyIERMask = 0x0010; 

  // PIE group 5 classified as zero latency
 
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
The behavior of clearInterrupt depends on whether the intNum is a PIE interrupt number. If so, the corresponding PIEIFR bit is cleared. If not (1 <= intNum <= 14), the corresponding IFR bit is cleared.
 
Hwi_disable()  // module-wide

Globally disable interrupts

C synopsis target-domain
macro UInt Hwi_disable();
 
RETURNS
opaque key for use by Hwi_restore()
DETAILS
Hwi_disable globally disables hardware interrupts and returns an opaque key indicating whether interrupts were globally enabled or disabled on entry to Hwi_disable(). The actual value of the key is target/device specific and is meant to be passed to Hwi_restore().
Call Hwi_disable before a portion of a function that needs to run without interruption. When critical processing is complete, call Hwi_restore or Hwi_enable to reenable hardware interrupts.
Servicing of interrupts that occur while interrupts are disabled is postponed until interrupts are reenabled. However, if the same type of interrupt occurs several times while interrupts are disabled, the interrupt's function is executed only once when interrupts are reenabled.
A context switch can occur when calling Hwi_enable or Hwi_restore if an enabled interrupt occurred while interrupts are disabled.
Hwi_disable may be called from main(). However, since Hwi interrupts are already disabled in main(), such a call has no effect.
CONSTRAINTS
If a Task switching API such as Semaphore_pend(), Semaphore_post(), Task_sleep(), or Task_yield() is invoked which results in a context switch while interrupts are disabled, an embedded call to Hwi_enable occurs on the way to the new thread context which unconditionally re-enables interrupts. Interrupts will remain enabled until a subsequent Hwi_disable invocation.
Swis always run with interrupts enabled. See Swi_post() for a discussion Swis and interrupts.
 
Hwi_disableIER()  // module-wide

Disable certain maskable interrupts

C synopsis target-domain
Bits16 Hwi_disableIER(Bits16 mask);
 
ARGUMENTS
mask — bitmask of interrupts to disable
RETURNS
previous IER settings bitmask
DETAILS
Atomically disables specific interrupts by clearing the bits specified by mask in the Interrupt Enable Register (IER).
The IER bits to be cleared should be set to 1 in the mask.
 
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
The behavior of Hwi_disableInterrupt depends on whether the intNum is a PIE interrupt number. If so, the appropriate bit in its group's PIEIER register is cleared. Note that, unlike enableInterrupt, disableInterrupt does not touch IER bits when operating upon a PIE interrupt number. If intNum is a non-PIE interrupt (1 <= intNum <= 14), then the corresponding bit in the IER register is cleared.
The return value is a key whose value reflects the previous state of the PIEIER bit.
 
Hwi_disablePIEIER()  // module-wide

Disable interrupts in a PIE group

C synopsis target-domain
Bits16 Hwi_disablePIEIER(UInt groupNum, Bits16 pieMask);
 
ARGUMENTS
groupNum — PIE group number
pieMask — PIEIER disable mask for group
RETURNS
Previous PIEIER settings bitmask
DETAILS
Atomically disable PIE interrupts in a single PIE group according to supplied PIEIER bitmask
 
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_enableIER()  // module-wide

Enable certain maskable interrupts

C synopsis target-domain
Bits16 Hwi_enableIER(Bits16 mask);
 
ARGUMENTS
mask — Bitmask of interrupts to enable
RETURNS
Previous IER settings bitmask
DETAILS
Atomically enables specific interrupts by setting the bits specified by mask in the Interrupt Enable Register (IER).
The IER bits to be set should be set to 1 in the mask.
 
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
The behavior of enableInterrupt depends on whether the intNum is a PIE interrupt number. If so, two operations are performed. The IER bit for intNum's PIE group is set and the appropriate bit in its group's PIEIER register is also set. However, if intNum is a non-PIE interrupt (1 <= intNum <= 14), then the corresponding bit in the IER register is set.
The return value is a key whose value reflects the previous state of the PIEIER bit. Note that the key does not reflect the IER register's previous state even if its state is modified by this call.
 
Hwi_enablePIEIER()  // module-wide

Enable interrupts in a PIE group

C synopsis target-domain
Bits16 Hwi_enablePIEIER(UInt groupNum, Bits16 pieMask);
 
ARGUMENTS
groupNum — PIE group number
pieMask — PIEIER enable mask for group
RETURNS
Previous PIEIER settings bitmask
DETAILS
Atomically enable PIE interrupts in a single PIE group according to supplied PIEIER bitmask
 
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
RETURNS
Hwi handle associated with intNum
 
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 an interrupt vector with an ISR address

C synopsis target-domain
Void Hwi_plug(UInt intNum, Hwi_PlugFuncPtr fxn);
 
ARGUMENTS
intNum — interrupt number
fxn — pointer to ISR function
DETAILS
plug hooks up the specified function as the branch target for a hardware interrupt (fielded by the CPU) at the vector address corresponding to intNum. plug does not enable the interrupt. Use Hwi_enableIER to enable specific interrupts.
This API can plug the full set of vectors supported by the PIE (0-127).
 
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_restoreIER()  // module-wide

Restore maskable interrupts

C synopsis target-domain
Bits16 Hwi_restoreIER(Bits16 mask);
 
ARGUMENTS
mask — Bitmask of interrupts to restore
RETURNS
Previous IER settings bitmask
DETAILS
Restores maskable interrupts to the state they were in when either disableIER() or enableIER() was called.
Atomically writes the given mask to the IER register. Typically used to restore the IER register to the state returned from a call to either disableIER() or enableIER().
 
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
The behavior of restoreInterrupt depends on whether the intNum is a PIE interrupt number. If so, the supplied key returned by an earlier call to disableInterrupt and enableInterrupt is used to restore the corresponding PIEIER bit to its state before the earlier call. However, if intNum is a non-PIE interrupt (1 <= intNum <= 14), then the corresponding bit in the IER register is restored using the key.
 
Hwi_restorePIEIER()  // module-wide

Restores interrupts in a PIE group

C synopsis target-domain
Bits16 Hwi_restorePIEIER(UInt groupNum, Bits16 pieMask);
 
ARGUMENTS
groupNum — PIE group number
pieMask — PIEIER restore mask for group
RETURNS
Previous PIEIER settings bitmask
DETAILS
Atomically restore PIE interrupts in a single PIE group according to supplied PIEIER bitmask
 
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
    Bits16 disableMask;
    // Dispatcher auto-nesting interrupt disable mask
    Bool enableAck;
    // Enable automatic acknowledgement of PIE interrupts by the Hwi interrupt dispatcher
    Bool enableInt;
    // Enable this interrupt when object is created? Default is true
    Int eventId;
    // Interrupt event ID (Interrupt Selection Number)
    IHwi_MaskingOption maskSetting;
    // maskSetting. Default is Hwi_MaskingOption_SELF
    Int priority;
    // Interrupt priority. Not supported on this target
    Bits16 restoreMask;
    // Dispatcher auto-nesting interrupt restore mask
} 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.disableMask  // instance

Dispatcher auto-nesting interrupt disable mask

C synopsis target-domain
struct Hwi_Params {
      ...
    Bits16 disableMask;
 
DETAILS
When the dispatcher's auto interrupt nesting support feature is enabled (see dispatcherAutoNestingSupport), this mask defines which IER bits are disabled prior to invoking the user's ISR function with GIE = 1.
disableMask bits set to 1 correspond to IER bits that will be cleared prior to invoking the ISR.
The value of this mask is normally auto-calculated based on the value of the maskSetting. However, manual setting of this mask is enabled by setting the maskSetting to MaskingOption_BITMASK.
The default value is derived from the MaskingOption_SELF maskSetting.
 
config Hwi_Params.enableAck  // instance

Enable automatic acknowledgement of PIE interrupts by the Hwi interrupt dispatcher

C synopsis target-domain
struct Hwi_Params {
      ...
    Bool enableAck;
 
 
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

maskSetting. Default is Hwi_MaskingOption_SELF

C synopsis target-domain
struct Hwi_Params {
      ...
    IHwi_MaskingOption maskSetting;
 
 
config Hwi_Params.priority  // instance

Interrupt priority. Not supported on this target

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.
 
config Hwi_Params.restoreMask  // instance

Dispatcher auto-nesting interrupt restore mask

C synopsis target-domain
struct Hwi_Params {
      ...
    Bits16 restoreMask;
 
DETAILS
When the dispatcher's auto interrupt nesting support feature is enabled (see dispatcherAutoNestingSupport), this mask defines which IER bits are restored to their previous setting upon return from the user's ISR function.
restoreMask bits set to 1 correspond to IER bits that will be restored.
The value of this mask is normally auto-calculated based on the value of the maskSetting. However, manual setting of this mask is enabled by setting the maskSetting to MaskingOption_BITMASK.
The default value is derived from the MaskingOption_SELF maskSetting.
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.
CONSTRAINTS
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);
 
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/c28/Hwi.xdc
var Hwi = xdc.useModule('ti.sysbios.family.c28.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.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.intNum = Int  ...
        obj.fxn = Void(*)(Void)  ...
        obj.enableInt = Bool  ...
 
        obj.hwiStackPeak = SizeT  ...
        obj.hwiStackSize = SizeT  ...
        obj.hwiStackBase = Ptr  ...
module-wide config parameters
        msg: "A_badIntNum: Invalid interrupt number"
    };
        msg: "A_invalidArg: Invalid argument"
    };
        msg: "A_zeroLatencyConflict: Conflict with zero latency IER mask"
    };
        msg: "E_alreadyDefined: Hwi already defined: intr# %d"
    };
        msg: "E_unpluggedInterrupt: Unplugged interrupt flagged: intr# %d"
    };
        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"
    };
 
module-wide functions
    Hwi.plugMeta// Statically plug an interrupt vector with an ISR address(UInt intNum, Void(*)(Void) fxn) returns Void
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);
 
 
const Hwi.NUM_INTERRUPTS

C28 supports 32 interrupts

Configuration settings
const Hwi.NUM_INTERRUPTS = 32;
 
C SYNOPSIS
 
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.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
 
metaonly struct Hwi.NonDispatchedInterrupt

Non-dispatched interrupt object

Configuration settings
var obj = new Hwi.NonDispatchedInterrupt;
 
    obj.intNum = Int  ...
    obj.fxn = Void(*)(Void)  ...
    obj.enableInt = Bool  ...
 
FIELDS
intNum — Interrupt number
fxn — Non-dispatched interrupt service routine (ISR)
enableInt — Enable the interrupt after plugging the vector
DETAILS
Provided so that XGCONF users can easily plug non-dispatched interrupts
 
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_badIntNum  // module-wide

Assert raised when an invalid interrupt number is passed to a Hwi call

Configuration settings
Hwi.A_badIntNum = Assert.Desc {
    msg: "A_badIntNum: Invalid interrupt number"
};
 
C SYNOPSIS
 
config Hwi.A_invalidArg  // module-wide

Assert raised when an invalid argument has been passed to a function

Configuration settings
Hwi.A_invalidArg = Assert.Desc {
    msg: "A_invalidArg: Invalid argument"
};
 
C SYNOPSIS
 
config Hwi.A_zeroLatencyConflict  // module-wide

Assert raised when there is a conflict with the zero latency IER mask

Configuration settings
Hwi.A_zeroLatencyConflict = Assert.Desc {
    msg: "A_zeroLatencyConflict: Conflict with zero latency IER mask"
};
 
DETAILS
This assert is raised when trying to create a Hwi with an intNum that conflicts with the supplied zero latency IER mask.
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_unpluggedInterrupt  // module-wide

Error raised when an unplugged interrupt is flagged

Configuration settings
Hwi.E_unpluggedInterrupt = Error.Desc {
    msg: "E_unpluggedInterrupt: Unplugged interrupt flagged: intr# %d"
};
 
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_ALL  // module-wide
Configuration settings
Hwi.NUM_INTERRUPTS_ALL = Int Hwi.NUM_INTERRUPTS + Hwi.NUM_INTERRUPTS_PIE;
 
C SYNOPSIS
 
config Hwi.NUM_INTERRUPTS_PIE  // module-wide

C28 supports 96 PIE interrupts

Configuration settings
Hwi.NUM_INTERRUPTS_PIE = Int 96;
 
DETAILS
Note: TMS320F2837X devices have an enhanced PIE that supports 196 PIE interrupts. This config param is set to 192 by default.
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.zeroLatencyIERMask  // module-wide

Zero Latency IER Mask

Configuration settings
Hwi.zeroLatencyIERMask = Bits16 0x0;
 
DETAILS
CPU interrupts specified in this mask (which corresponds to the 16-bit IER register) are carefully managed so that they are disabled for only the bare minimum time required to safely manipulated the IER register. This means that the disable, enable, and restore calls leave the zero latency CPU interrupts enabled after being called. Zero latency operation may be used to ensure minimal interrupt-to-ISR time for non-BIOS interrupt handlers in applications that demand low latency.
NOTE
While referred to as "Zero Latency Interrupts", the interrupts specified in the zeroLatencyIERMask are NOT TRULY ZERO LATENCY! They are still disabled briefly in software by the Hwi_disable(), Hwi_restore(), and Hwi_enable() APIs while the IER register bits are manipulated. Additionally, interrupts are globally disabled automatically by the 28x hardware when an interrupt is taken. The Hwi module's interrupt dispatcher quickly (ie: within 30 instructions) re-enables interrupts globally after carefully manipulating the IER register accordingly.
It is important to note that zero latency and non-zero latency PIE interrupts may not share a common PIE group. The entire PIE group whose bit is set in the zeroLatencyIERMask will be treated as zero latency.
WARNING
Enabling zero latency mode (specifying a non-zero zeroLatencyIERMask) generates alternate (and slower) code used to disable, enable and restore interrupts. This alternate code will maintain a shadow copy of interrupt state (IER register and global interrupt state). disableIER, enableIER and restoreIER will update both the IER register and its shadow. The disable call will copy the zero latency IER mask (supplied here) into the IER register. The enable call will copy the contents of the shadow IER register into the actual register. The restore call may either disable or enable the non-zero-latency interrupts.
It is important to be aware of the performance penalty associated with using zero latency interrupts before using this feature.
Example:
  var Hwi = xdc.useModule('ti.sysbios.family.c28.Hwi');
  Hwi.zeroLatencyIERMask = 0x0010; 

  // PIE group 5 classified as zero latency
C SYNOPSIS
 
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.nonDispatchedInterrupts  // module-wide

Non-dispatched interrupt array

Configuration settings
Hwi.nonDispatchedInterrupts = Hwi.NonDispatchedInterrupt[string] undefined;
 
DETAILS
Provided so that XGCONF users can easily plug non-dispatched interrupts
 
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.
 
metaonly Hwi.plugMeta()  // module-wide

Statically plug an interrupt vector with an ISR address

Configuration settings
Hwi.plugMeta(UInt intNum, Void(*)(Void) fxn) returns Void
 
ARGUMENTS
intNum — Interrupt number
fxn — Pointer to ISR function
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.disableMask = Bits16 0;
    // Dispatcher auto-nesting interrupt disable mask
    params.enableAck = Bool true;
    // Enable automatic acknowledgement of PIE interrupts by the Hwi interrupt dispatcher
    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_SELF;
    // maskSetting. Default is Hwi_MaskingOption_SELF
    params.priority = Int 0;
    // Interrupt priority. Not supported on this target
    params.restoreMask = Bits16 0;
    // Dispatcher auto-nesting interrupt restore mask
 
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.disableMask  // instance

Dispatcher auto-nesting interrupt disable mask

Configuration settings
var params = new Hwi.Params;
  ...
params.disableMask = Bits16 0;
 
DETAILS
When the dispatcher's auto interrupt nesting support feature is enabled (see dispatcherAutoNestingSupport), this mask defines which IER bits are disabled prior to invoking the user's ISR function with GIE = 1.
disableMask bits set to 1 correspond to IER bits that will be cleared prior to invoking the ISR.
The value of this mask is normally auto-calculated based on the value of the maskSetting. However, manual setting of this mask is enabled by setting the maskSetting to MaskingOption_BITMASK.
The default value is derived from the MaskingOption_SELF maskSetting.
C SYNOPSIS
 
config Hwi.Params.enableAck  // instance

Enable automatic acknowledgement of PIE interrupts by the Hwi interrupt dispatcher

Configuration settings
var params = new Hwi.Params;
  ...
params.enableAck = Bool true;
 
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

maskSetting. Default is Hwi_MaskingOption_SELF

Configuration settings
var params = new Hwi.Params;
  ...
 
C SYNOPSIS
 
config Hwi.Params.priority  // instance

Interrupt priority. Not supported on this target

Configuration settings
var params = new Hwi.Params;
  ...
params.priority = Int 0;
 
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.
C SYNOPSIS
 
config Hwi.Params.restoreMask  // instance

Dispatcher auto-nesting interrupt restore mask

Configuration settings
var params = new Hwi.Params;
  ...
params.restoreMask = Bits16 0;
 
DETAILS
When the dispatcher's auto interrupt nesting support feature is enabled (see dispatcherAutoNestingSupport), this mask defines which IER bits are restored to their previous setting upon return from the user's ISR function.
restoreMask bits set to 1 correspond to IER bits that will be restored.
The value of this mask is normally auto-calculated based on the value of the maskSetting. However, manual setting of this mask is enabled by setting the maskSetting to MaskingOption_BITMASK.
The default value is derived from the MaskingOption_SELF maskSetting.
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 Thu, 25 May 2017 22:09:25 GMT