interface ti.sysbios.interfaces.IHwi

Hardware Interrupt Support Module

The IHwi interface specifies APIs for globally enabling, disabling, and restoring interrupts. [ more ... ]
XDCspec summary sourced in ti/sysbios/interfaces/IHwi.xdc
interface IHwi {  ...
// inherits xdc.runtime.IModule
instance:  ...
XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
 
interface IHwi {
module-wide constants & types
        MaskingOption_NONE,
        MaskingOption_ALL,
        MaskingOption_SELF,
        MaskingOption_BITMASK,
        MaskingOption_LOWER
    };
 
    typedef Void (*FuncPtr// Hwi create function type definition)(UArg);
    typedef UArg Irp// Interrupt Return Pointer;
 
        Void (*registerFxn)(Int);
        Void (*createFxn)(IHwi.Handle,Error.Block*);
        Void (*beginFxn)(IHwi.Handle);
        Void (*endFxn)(IHwi.Handle);
        Void (*deleteFxn)(IHwi.Handle);
    };
 
        SizeT hwiStackPeak;
        SizeT hwiStackSize;
        Ptr hwiStackBase;
    };
module-wide config parameters
 
module-wide functions
    Void clearInterrupt// Clear a specific interrupt(UInt intNum);
    UInt disable// ();
    UInt enableInterrupt// Enable a specific interrupt(UInt intNum);
    Bool getCoreStackInfo// Get Hwi stack usage Info for the specified coreId(IHwi.StackInfo *stkInfo, Bool computeStackDepth, UInt coreId);
    Bool getStackInfo// Get Hwi stack usage Info(IHwi.StackInfo *stkInfo, Bool computeStackDepth);
    Void restore// Globally restore interrupts(UInt key);
 
 
 
instance:
per-instance config parameters
    config UArg arg// ISR function argument. Default is 0 = 0;
    config Int priority// Interrupt priority = -1;
per-instance creation
    create// Create an instance-object(Int intNum, IHwi.FuncPtr hwiFxn);
per-instance functions
    Void setHookContext// Set hook instance's context for a Hwi(Int id, Ptr hookContext);
}
DETAILS
The IHwi interface specifies APIs for globally enabling, disabling, and restoring interrupts.
Additionally, management of individual, device-specific hardware interrupts is provided.
The user can statically or dynamically assign routines that run when specific hardware interrupts occur.
Dynamic assignment of Hwi routines to interrupts at run-time is done using the Hwi_create function.
Interrupt routines can be written completely in C, completely in assembly, or in a mix of C and assembly. In order to support interrupt routines written completely in C, an interrupt dispatcher is provided that performs the requisite prolog and epilog for an interrupt routine.
Some routines are assigned to interrupts by the other SYS/BIOS modules. For example, the Clock module configures its own timer interrupt handler. See the Clock Module for more details.
RUNTIME HWI CREATION
Below is an example of configuring an interrupt at runtime. Usually this code would be placed in main().
  #include <xdc/runtime/Error.h>
  #include <ti/sysbios/hal/Hwi.h>
  
  Hwi_Handle myHwi;
  
  Int main(Int argc, char* argv[])
  {
      Hwi_Params hwiParams;
      Error_Block eb;
   
      Hwi_Params_init(&hwiParams);
      Error_init(&eb);
  
      // set the argument you want passed to your ISR function
      hwiParams.arg = 1;        
   
      // set the event id of the peripheral assigned to this interrupt
      hwiParams.eventId = 10;   
   
      // don't allow this interrupt to nest itself
      hwiParams.maskSetting = Hwi_MaskingOption_SELF;
   
      // 
      // Configure interrupt 5 to invoke "myIsr".
      // Automatically enables interrupt 5 by default
      // set params.enableInt = FALSE if you want to control
      // when the interrupt is enabled using Hwi_enableInterrupt()
      //
   
      myHwi = Hwi_create(5, myIsr, &hwiParams, &eb);
   
      if (Error_check(&eb)) {
          // handle the error
      }
  }
   
  Void myIsr(UArg arg)
  {
      // here when interrupt #5 goes off
  }
HOOK FUNCTIONS
Sets of hook functions can be specified for the Hwi module using the configuration tool. Each set contains these hook functions:
  • Register: A function called before any statically-created Hwis are initialized at runtime. The register hook is called at boot time before main() and before interrupts are enabled.
  • Create: A function that is called when a Hwi is created. This includes hwis that are created statically and those created dynamically using Hwi_create.
  • Begin: A function that is called just prior to running a Hwi.
  • End: A function that is called just after a Hwi finishes.
  • Delete: A function that is called when a Hwi is deleted at run-time with Hwi_delete.
Register Function
The Register function is provided to allow a hook set to store its hookset ID. This id can be passed to Hwi_setHookContext and Hwi_getHookContext to set or get hookset-specific context. The Register function must be specified if the hook implementation needs to use Hwi_setHookContext or Hwi_getHookContext. The registerFxn hook function is called during system initialization before interrupts have been enabled.
  Void myRegisterFxn(Int id);
Create and Delete Functions
The create and delete functions are called whenever a Hwi is created or deleted. They are called with interrupts enabled (unless called at boot time or from main()).
  Void myCreateFxn(Hwi_Handle hwi, Error_Block *eb);
  Void myDeleteFxn(Hwi_Handle hwi);
Begin and End Functions
The beginFxn and endFxn function hooks are called with interrupts globally disabled, therefore any hook processing function will contribute to the overall system interrupt response latency. In order to minimize this impact, carefully consider the processing time spent in an Hwi beginFxn or endFxn function hook.
  Void myBeginFxn(Hwi_Handle hwi);
  Void myEndFxn(Hwi_Handle hwi);
Hook functions can only be configured statically.
 
enum IHwi.MaskingOption

Shorthand interrupt masking options

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
enum MaskingOption {
    MaskingOption_NONE,
    MaskingOption_ALL,
    MaskingOption_SELF,
    MaskingOption_BITMASK,
    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.
 
typedef IHwi.FuncPtr

Hwi create function type definition

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
typedef Void (*FuncPtr)(UArg);
 
 
typedef IHwi.Irp

Interrupt Return Pointer

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
typedef UArg Irp;
 
DETAILS
This is the address of the interrupted instruction.
 
struct IHwi.HookSet

Hwi hook set type definition

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
struct HookSet {
    Void (*registerFxn)(Int);
    Void (*createFxn)(IHwi.Handle,Error.Block*);
    Void (*beginFxn)(IHwi.Handle);
    Void (*endFxn)(IHwi.Handle);
    Void (*deleteFxn)(IHwi.Handle);
};
 
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 IHwi.StackInfo

Structure contains Hwi stack usage info

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
struct StackInfo {
    SizeT hwiStackPeak;
    SizeT hwiStackSize;
    Ptr hwiStackBase;
};
 
DETAILS
Used by getStackInfo() and viewGetStackInfo() functions
 
config IHwi.dispatcherAutoNestingSupport  // module-wide

Include interrupt nesting logic in interrupt dispatcher?

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
config Bool dispatcherAutoNestingSupport = 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.
 
config IHwi.dispatcherIrpTrackingSupport  // module-wide

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

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
config Bool dispatcherIrpTrackingSupport = 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.
 
config IHwi.dispatcherSwiSupport  // module-wide

Include Swi scheduling logic in interrupt dispatcher?

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
config Bool 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 IHwi.dispatcherTaskSupport  // module-wide

Include Task scheduling logic in interrupt dispatcher?

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
config Bool 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.
 
metaonly config IHwi.common$  // module-wide

Common module configuration parameters

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
metaonly config Types.Common$ common$;
 
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
 
IHwi.clearInterrupt()  // module-wide

Clear a specific interrupt

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
Void clearInterrupt(UInt intNum);
 
ARGUMENTS
intNum — interrupt number to clear
DETAILS
Clears a specific interrupt's pending status. The implementation is family-specific.
 
IHwi.disable()  // module-wide
XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
UInt disable();
 
 
IHwi.disableInterrupt()  // module-wide

Disable a specific interrupt

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
UInt disableInterrupt(UInt intNum);
 
ARGUMENTS
intNum — interrupt number to disable
RETURNS
key to restore previous enable/disable state
DETAILS
Disable a specific interrupt identified by an interrupt number.
 
IHwi.enable()  // module-wide

Globally enable interrupts

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
UInt enable();
 
RETURNS
opaque key for use by Hwi_restore()
DETAILS
Hwi_enable globally enables hardware interrupts and returns an opaque key indicating whether interrupts were globally enabled or disabled on entry to Hwi_enable(). The actual value of the key is target/device specific and is meant to be passed to Hwi_restore().
This function is called as part of 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().
 
IHwi.enableInterrupt()  // module-wide

Enable a specific interrupt

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
UInt enableInterrupt(UInt intNum);
 
ARGUMENTS
intNum — interrupt number to enable
RETURNS
key to restore previous enable/disable state
DETAILS
Enables a specific interrupt identified by an interrupt number.
 
IHwi.getCoreStackInfo()  // module-wide

Get Hwi stack usage Info for the specified coreId

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
Bool 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);
  }
 
IHwi.getStackInfo()  // module-wide

Get Hwi stack usage Info

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
Bool 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);
  }
 
IHwi.post()  // module-wide

Generate an interrupt for test purposes

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
Void post(UInt intNum);
 
ARGUMENTS
intNum — ID of interrupt to generate
 
IHwi.restore()  // module-wide

Globally restore interrupts

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
Void restore(UInt key);
 
ARGUMENTS
key — enable/disable state to restore
DETAILS
Hwi_restore globally restores interrupts to the state determined by the key argument provided by a previous invocation of Hwi_disable.
A context switch may occur when calling Hwi_restore if Hwi_restore reenables interrupts and another Hwi occurred while interrupts were disabled.
Hwi_restore may be called from main(). However, since Hwi_enable cannot be called from main(), interrupts are always disabled in main(), and a call to Hwi_restore has no effect.
 
IHwi.restoreInterrupt()  // module-wide

Restore a specific interrupt's enabled/disabled state

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
Void restoreInterrupt(UInt intNum, UInt key);
 
ARGUMENTS
intNum — interrupt number to restore
key — key returned from enableInt or disableInt
DETAILS
Restores a specific interrupt identified by an interrupt number. restoreInterrupt is generally used to restore an interrupt to its state before disableInterrupt or enableInterrupt was invoked
 
IHwi.startup()  // module-wide

Initially enable interrupts

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
Void startup();
 
DETAILS
Called within BIOS_start
 
metaonly IHwi.addHookSet()  // module-wide

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

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
metaonly Void addHookSet(IHwi.HookSet hook);
 
ARGUMENTS
hook — structure of type HookSet
DETAILS
HookSet structure elements may be omitted, in which case those elements will not exist.
 
config IHwi.Params.arg  // instance

ISR function argument. Default is 0

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
config UArg arg = 0;
 
 
config IHwi.Params.enableInt  // instance

Enable this interrupt when object is created? Default is true

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
config Bool enableInt = true;
 
 
config IHwi.Params.eventId  // instance

Interrupt event ID (Interrupt Selection Number)

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
config Int eventId = -1;
 
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
 
config IHwi.Params.maskSetting  // instance

maskSetting. Default is Hwi_MaskingOption_SELF

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
 
 
config IHwi.Params.priority  // instance

Interrupt priority

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
config Int priority = -1;
 
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.
Static Instance Creation

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
create(Int intNum, IHwi.FuncPtr hwiFxn);
// Create an instance-object
ARGUMENTS
intNum — interrupt number
hwiFxn — pointer to ISR function
DETAILS
A Hwi dispatcher table entry is created and filled with the function specified by the fxn parameter and the attributes specified by the params parameter.
If params is NULL, the Hwi's dispatcher properties are assigned a default set of values. Otherwise, the 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.
 
IHwi.getFunc()  // instance

Get Hwi function and arg

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
IHwi.FuncPtr getFunc(UArg *arg);
 
ARGUMENTS
arg — pointer for returning hwi's ISR function argument
RETURNS
hwi's ISR function
 
IHwi.getHookContext()  // instance

Get hook instance's context for a Hwi

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
Ptr getHookContext(Int id);
 
RETURNS
hook instance's context for hwi
 
IHwi.getIrp()  // instance

Get address of interrupted instruction

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
IHwi.Irp getIrp();
 
RETURNS
most current IRP of a Hwi
 
IHwi.setFunc()  // instance

Overwrite Hwi function and arg

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
Void setFunc(IHwi.FuncPtr fxn, UArg arg);
 
ARGUMENTS
fxn — pointer to ISR function
arg — argument to ISR function
DETAILS
Replaces a Hwi object's hwiFxn function originally provided in create.
 
IHwi.setHookContext()  // instance

Set hook instance's context for a Hwi

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
Void setHookContext(Int id, Ptr hookContext);
 
ARGUMENTS
id — hook instance's ID
hookContext — value to write to context
generated on Fri, 10 Jun 2016 23:29:35 GMT