module ti.sysbios.family.arm.v7r.vim.Hwi

Hardware Interrupt Support Module

C synopsis
Individual elements
DETAILS
MINIMAL LATENCY INTERRUPTS
INTERRUPT CHANNEL CONFIGURATION
MORE HWI EXAMPLES
Configuration settings
Individual elements

This Hwi module provides Hercules VIM specific implementations of the APIs defined in IHwi. [ more ... ]

C synopsis target-domain sourced in ti/sysbios/family/arm/v7r/vim/Hwi.xdc

#include <ti/sysbios/family/arm/v7r/vim/Hwi.h>

Functions
Void	Hwi_construct// Initialize a new instance object inside the provided structure(Hwi_Struct structP, Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params params, Error_Block *eb);
Hwi_Handle	Hwi_create// Allocate and initialize a new instance object and return its handle(Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params params, Error_Block eb);
Void	Hwi_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Hwi_Handle *handleP);
Void	Hwi_destruct// Finalize the instance object inside the provided structure(Hwi_Struct *structP);
UInt	Hwi_disableIRQ// Disable IRQ interrupts();
UInt	Hwi_enableIRQ// Enable IRQ interrupts();
Hwi_Object *	Hwi_getHandle// Returns pointer to Hwi instance object(UInt intNum);
Void	Hwi_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Hwi_Params *params);
Void	Hwi_reconfig// Reconfigure a dispatched interrupt(Hwi_Handle handle, Hwi_FuncPtr fxn, Hwi_Params *params);
Void	Hwi_restoreIRQ// Restore IRQ interrupts(UInt key);
Functions common to all IHwi modules
Void	Hwi_clearInterrupt// Clear a specific interrupt(UInt intNum);
macro UInt	Hwi_disable// Globally disable interrupts();
UInt	Hwi_disableInterrupt// Disable a specific interrupt(UInt intNum);
macro UInt	Hwi_enable// Globally enable interrupts();
UInt	Hwi_enableInterrupt// Enable a specific interrupt(UInt intNum);
Bool	Hwi_getCoreStackInfo// Get Hwi stack usage Info for the specified coreId(IHwi_StackInfo *stkInfo, Bool computeStackDepth, UInt coreId);
IHwi_FuncPtr	Hwi_getFunc// Get Hwi function and arg(Hwi_Handle handle, UArg *arg);
Ptr	Hwi_getHookContext// Get hook instance's context for a Hwi(Hwi_Handle handle, Int id);
IHwi_Irp	Hwi_getIrp// Get address of interrupted instruction(Hwi_Handle handle);
Bool	Hwi_getStackInfo// Get Hwi stack usage Info(IHwi_StackInfo *stkInfo, Bool computeStackDepth);
Void	Hwi_post// Generate an interrupt for test purposes(UInt intNum);
macro Void	Hwi_restore// Globally restore interrupts(UInt key);
Void	Hwi_restoreInterrupt// Restore a specific interrupt's enabled/disabled state(UInt intNum, UInt key);
Void	Hwi_setFunc// Overwrite Hwi function and arg(Hwi_Handle handle, IHwi_FuncPtr fxn, UArg arg);
Void	Hwi_setHookContext// Set hook instance's context for a Hwi(Hwi_Handle handle, Int id, Ptr hookContext);
Void	Hwi_startup// Initially enable interrupts();
Functions common to all target instances
	Hwi_handle// Convert this instance structure pointer into an instance handle, Hwi_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, Hwi_Handle_label// The label associated with this instance object, Hwi_Handle_name// The name of this instance object, Hwi_Handle_upCast// unconditionally move one level up the inheritance hierarchy, Hwi_Object_count// The number of statically-created instance objects, Hwi_Object_first// The handle of the first dynamically-created instance object, or NULL, Hwi_Object_get// The handle of the i-th statically-created instance object (array == NULL), Hwi_Object_heap// The heap used to allocate dynamically-created instance objects, Hwi_Object_next// The handle of the next dynamically-created instance object, or NULL, Hwi_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
	Hwi_Module_getMask// Returns the diagnostics mask for this module, Hwi_Module_hasMask// Test whether this module has a diagnostics mask, Hwi_Module_heap// The heap from which this module allocates memory, Hwi_Module_id// Get this module's unique id, Hwi_Module_setMask// Set the diagnostics mask for this module, Hwi_Module_startupDone// Test if this module has completed startup
Typedefs
typedef Void	(*Hwi_FuncPtr// Hwi create function type definition)(UArg);
typedef Hwi_Object *	Hwi_Handle// Client reference to an instance object;
typedef struct	Hwi_HookSet// Hwi hook set type definition ...
typedef UArg	Hwi_Irp// Interrupt Return Pointer;
typedef enum	Hwi_MaskingOption// Shorthand interrupt masking options ...
typedef struct	Hwi_Object// Opaque internal representation of an instance object Hwi_Object;
typedef struct	Hwi_Params// Instance config-params structure ...
typedef struct	Hwi_StackInfo// Structure contains Hwi stack usage info ...
typedef struct	Hwi_Struct// Opaque client structure large enough to hold an instance object Hwi_Struct;
typedef enum	Hwi_Type// Interrupt type. IRQ or FIQ ...
typedef Void	(*Hwi_VectorFuncPtr// Hwi vector function type definition)(Void);
Constants
extern const Assert_Id	Hwi_A_badChannelId// Assert raised when an invalid channelId is passed to Hwi_mapChannel() function;
extern const Ptr	Hwi_core0VectorTableAddress// Determines the location of Core0's Interrupt Vector Table on a Dual-Core device. Default is device dependent;
extern const Ptr	Hwi_core1VectorTableAddress// Determines the location of Core1's Interrupt Vector Table on a Dual-Core device. Default is device dependent;
extern const Bool	Hwi_dispatcherAutoNestingSupport// Include interrupt nesting logic in interrupt dispatcher?;
extern const Bool	Hwi_dispatcherIrpTrackingSupport// Controls whether the dispatcher retains the interrupted thread's return address;
extern const Bool	Hwi_dispatcherSwiSupport// Include Swi scheduling logic in interrupt dispatcher?;
extern const Bool	Hwi_dispatcherTaskSupport// Include Task scheduling logic in interrupt dispatcher?;
extern const Error_Id	Hwi_E_alreadyDefined// Error raised when Hwi is already defined;
extern const Error_Id	Hwi_E_badIntNum// Error raised if an attempt is made to create a Hwi with an interrupt number greater than Hwi_NUM_INTERRUPTS - 1;
extern const Error_Id	Hwi_E_undefined// Error raised when an undefined interrupt has fired;
extern const Error_Id	Hwi_E_unsupportedMaskingOption// Error raised when an unsupported Hwi.MaskingOption used;
extern const Ptr	Hwi_fiqStack// FIQ stack pointer. Default = null. (Indicates that stack is to be created using staticPlace());
extern const Ptr	Hwi_irqStack// Non dispatched IRQ stack pointer. Default = null. (Indicates that stack is to be created using staticPlace());
extern const Log_Event	Hwi_LD_end// Issued just after return from Hwi function (with interrupts disabled);
extern const Log_Event	Hwi_LM_begin// Issued just prior to Hwi function invocation (with interrupts disabled);
extern const UInt	Hwi_NUM_INTERRUPTS// ;

DETAILS

This Hwi module provides Hercules VIM specific implementations of the APIs defined in IHwi.

Additional ARM device-specific APIs are also provided.

MINIMAL LATENCY INTERRUPTS

For applications requiring extremely low interrupt latency, this Hwi module allows the user to create FIQ interrupts that bypass the SYS/BIOS interrupt dispatcher. Though not a precisely correct classification, these interrupts are referred to as "Zero latency" interrupts.

"FIQ" aka "Zero latency" interrupts can be created by setting the Hwi_Param type to Hwi_Type_FIQ. FIQ interrupts offer low interrupt latency as they do not have to pass through the regular SYS/BIOS interrupt dispatcher and are always enabled. When auto nesting is enabled and masking option ALL or LOWER is used, some or all of the VIM interrupt channels will be disabled while the interrupt is being serviced. However, none of the channels corresponding to "Zero latency" interrupts are disabled (masked).

The ISR handler function for a "Zero latency" interrupt must use the "interrupt" keyword in the function definition and should have no parameters. Using the "interrupt" keyword will ensure that the necessary registers are saved on entry into the interrupt routine and are restored upon exit from the interrupt routine.

Since the function pointer passed to Hwi_create()/Hwi_construct() has a different function signature (i.e. it accepts an argument), the "Zero latency" function must be type-casted to Hwi_FuncPtr type before being passed to Hwi_create()/Hwi_construct() in order to avoid any compiler warnings.

Unlike regular IRQ interrupts, FIQ interrupts do not run on the System stack but on their own FIQ stack. The stack pointer, size and section name for the FIQ stack can be set using the fiqStack, fiqStackSize and fiqStackSection module wide configuration params.

(Constraints of using "FIQ" aka "Zero latency" interrupts) Interrupts configured to bypass 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()

Here's an example showing how to create a Hwi of FIQ type:

  *.cfg:
  var Hwi = xdc.useModule('ti.sysbios.family.arm.v7r.vim.Hwi');
  Hwi.fiqStackSize = 2048;
  Hwi.fiqStackSection = ".myFiqStack"
  Program.sectMap[".myFiqStack"] = "RAM";

  *.c:
  #include <xdc/std.h>
  #include <xdc/runtime/System.h>

  #include <ti/sysbios/BIOS.h>
  #include <ti/sysbios/family/arm/v7r/vim/Hwi.h>

  #include <xdc/cfg/global.h>

  Void interrupt myIsrFIQ()
  {
      ...
  }

  Void main(Void)
  {
      Hwi_Params hwiParams;

      Hwi_Params_init(&hwiParams);
      hwiParams.type = Hwi_Type_FIQ;
      Hwi_create(INT_NUM_FIQ, (Hwi_FuncPtr)myIsrFIQ, &hwiParams, NULL);
      ...

      BIOS_start();
  }

(Non-dispatched interrupts) Cortex-R5 supports hardware vectored IRQ interrupts (i.e. interrupts are automatically dispatched to ISR). In order to leverage this feature for a given IRQ interrupt, the SYS/BIOS Hwi dispatcher needs to be bypassed for the particular interrupt. The Hwi params contain a useDispatcher param that can be used for this purpose.

When useDispatcher Hwi param is set to false, the Hwi function's address is written to the hardware interrupt vector table (VIM RAM). After an IRQ interrupt is received by the CPU, the CPU reads the address of the ISR directly from the VIM RAM and jumps to the function (See useDispatcher for more info).

INTERRUPT CHANNEL CONFIGURATION

Each VIM interrupt request (source) can be mapped to any of the interrupt channels (same as intNums). Lower numbered channels in each FIQ and IRQ have higher priority. Therefore, channel mapping provides a mechanism for prioritizing the interrupt requests.

Additionally, it is possible to configure a channel interrupt as a wakeup interrupt so it can bring the core out of low power mode (LPM).

This module has a Hwi.configChannelMeta() function that can be invoked from the cfg script to statically (at build time) change the channel mapping and wakeup functionality of a channel interrupt.

By default, all interrupt request sources are direct mapped to channels (i.e. interrupt request N is mapped to channel N) and wakeup feature is enabled for all interrupts.

Here's an example showing how to use this function:

  *.cfg:
  var Hwi = xdc.useModule('ti.sysbios.family.arm.v7r.vim.Hwi');

  // Map interrupt request line 86 to channel 2 (i.e. intNum 2) and disable
  // wakeup feature
  Hwi.configChannelMeta(2, 86, false);

MORE HWI EXAMPLES

Here's an example showing how to construct a Hwi at runtime:

  *.c:
  #include <ti/sysbios/family/arm/v7r/vim/Hwi.h>

  Hwi_Struct hwiStruct;

  Void myIsrIRQ(UArg arg)
  {
      ...
  }

  Void main(Void)
  {
      Hwi_Params hwiParams;

      Hwi_Params_init(&hwiParams);
      Hwi_construct(&hwiStruct, INT_NUM_IRQ, myIsrIRQ, &hwiParams, NULL);
      ...
      BIOS_start();
  }

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
disableIRQ	Y	Y	Y	Y	Y
enable	Y	Y	Y	N	N
enableInterrupt	Y	Y	Y	Y	N
enableIRQ	Y	Y	Y	N	N
getHandle	Y	Y	Y	Y	N
Params_init	Y	Y	Y	Y	Y
restore	Y	Y	Y	Y	Y
restoreInterrupt	Y	Y	Y	Y	Y
restoreIRQ	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
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).

enum Hwi_MaskingOption