How to use the Trap Function Hooks?

Macro to define the trap vector table. This macro is provided to define the trap vector table in the frameowrk. User shall not use this macro. Refer to the documentation to extend the trap with hook functions. How to use the Trap Function Hooks?. More...

Collaboration diagram for How to use the Trap Function Hooks?:

Macro to define the trap vector table. This macro is provided to define the trap vector table in the frameowrk. User shall not use this macro. Refer to the documentation to extend the trap with hook functions. How to use the Trap Function Hooks?.

This page describes how to use the trap function hooks with application framework.
Framework has built in Trap Service Routines, which has minimal set of debug information. The execution of trap service is as below,
1) When a trap occurs, a global structure variable "trapWatch" is updated with the information:
__a. Which CPU caused this trap,
__b. What is the trap class and
__c. What is the trap identification number
2) Call to a configurable hook function, passing structure trapWatch as parameter.
3) Then debug instruction executed.
4) Returning from the trap. (This instruction is not reached if debugger is connected because of "debug" instruction before)
For normal cases during development, where user works with debugger, user can watch the structure variable "trapWatch" in the debugger.

In case, user wants to make use of the information of trap for further processing,
extend the traps, using the hook functions provided.

Extending the traps with hook functions.

If the trap extensions are to be extended, it is very important to enable this feature. By default this feature is disabled.

How to enable the trap extension feature?

To extend the trap hook functions user must enable this feature by defining the macro "IFX_CFG_EXTEND_TRAP_HOOKS" in Ifx_Cfg.h, at path: 0_Src/0_AppSw/Config/Common/, as shown below.

//file: Ifx_Cfg.h

#define IFX_CFG_EXTEND_TRAP_HOOKS

Now the compiler will accept the further configurations to extend the hooks.
IfxCpu_Traps_Cfg.h file shall be used to extend the traps. This provide two kind of hook functions. ie. Hook for error traps and hooks (per CPU available) for system calls.

Extending the "Error traps" with hook function.

Error trap occurs as a result of an error event such as an instruction error, memory-management error or an illegal access.
To extend the error traps, following steps are to be followed:

Step1: Define a routine to substitute the hook for error traps.

This definition shall be as user defined code (Generally in DemoApps folder).
Considerations:

1. Format: IFX_INLINE void <trap extension name>(IfxCpu_Trap trapInfo)

   Note

   Define such a routine with the consideration that the trap extension hook is not a function. In case of context management error, this extension itself will not call any other function.

2. Use the information trapInfo, which is available as parameter passed to this hook and process further. Example code in a user defined file eg. Ifx_TrapExtension.h, placed under folder/subfolder: 0_AppSw/Tricore/DemoApp:

   //Example "inlined" function for trap Extension Hook.
   IFX_INLINE myTrapExtensionHook(IfxCpu_Trap trapInfo)
   {
     switch (trapInfo.tClass)
     {
       case IfxCpu_Trap_Class_memoryManagement:
       {
         //user code: Function calls allowed.
         break;
       }
       case IfxCpu_Trap_Class_internalProtection:
       {
         //user code: Function calls allowed.
         break;
       }
       case IfxCpu_Trap_Class_instructionErrors:
       {
         //user code: Function calls allowed.
         break;
       }
       case IfxCpu_Trap_Class_contextManagement:
       {
         //user code: Function calls NOT allowed.
         break;
       }
       case IfxCpu_Trap_Class_bus:
       {
         //user code: Function calls allowed.
         break;
       }
       case IfxCpu_Trap_Class_assertion:
       {
         //user code: Function calls allowed.
         break;
       }
       case IfxCpu_Trap_Class_nonMaskableInterrupt:
       {
         //user code: Function calls allowed.
         break;
       }
       case default:
       {
         break;
       }
     }
   }

   Note

   The error trap functions execute the debug instruction immediately after returning from extension hooks.

Step2: Configure error trap hook extension function.

Configure error trap hook extension function as defined above to the macro as below:

Note

Configuration of hook extension is available in IfxCpu_Trap_Cfg at path ../0_Src/0_AppSw/Tricore/McHalCfg/

//file: IfxCpu_Trap_Cfg.h

#include "Ifx_TrapExtension.h" //Assuming this is the file name as in above example

#define IFXCPU_TRAP_CFG_TSR_HOOK(trapInfo)  myTrapExtensionHook(trapInfo) //This is INLINE function.

Note

The exten hooks are effective only if this feature is enabled as explained in Ifx_Trap_Hooks_EnableExtn

Extending the cpu specific "system call" hook functions.

Tricore architecture provides the system call trap which is executed by software trigger. The instruction "syscall" triggers this trap. Please refer Tricore architecture manual for more details.
IfxCpu_trap driver provide hook function for each CPU separately. To extend System Call trap following steps are to be followed:

Step1: Define routine/s to substitute the hook/s for System Call trap.

This definition shall be as user defined code (Generally in DemoApps folder).
Considerations:

1. Format: void <syscall function name>(IfxCpu_Trap trapInfo) It is allowed to define this trap extension as function definition, because this trap is not triggered due to any error. Depending on the application requirement, define single or per CPU instance of the extension.
2. Use the information trapInfo which is available as parameter passed to this hook and process further. The parameter passed, with syscall instruction, will be trap identification number (refer to Tricore architecture manual for more details).

   Note

   To hook extension, information about trap identification number is available through parameter "trapInfo".

   Example code in a user defined file eg. Ifx_TrapExtension.h, placed under folder/subfolder: 0_AppSw/Tricore/DemoApp:

   //Example function for System Call Extension Hook.
   IFX_INLINE mySysCallExtensionHook(IfxCpu_Trap trapInfo)
   {
     switch (trapInfo.tId)
     {
       case 0:
       {
         //user code: Function calls allowed.
         break;
       }
       case 1:
       {
         //user code: Function calls allowed.
         break;
       }
       // and so on..
       case default:
       {
         break;
       }
     }
   }

Step2: Configure the extension function.\n

Configure the hook extension function defined above, to the macro as below:

Note

Configuration of hook extension is available in IfxCpu_Trap_Cfg file at path ../0_Src/0_AppSw/Tricore/McHalCfg/

//file: IfxCpu_Trap_Cfg.h

#include "Ifx_TrapExtension.h" //Assuming this is the file name as in above example

#define IFXCPU_TRAP_CFG_SYSCALL_CPU0_HOOK(trapInfo)  mySysCallExtensionHook(trapInfo)

#define IFXCPU_TRAP_CFG_SYSCALL_CPU1_HOOK(trapInfo)  // Not used in this example

#define IFXCPU_TRAP_CFG_SYSCALL_CPU2_HOOK(trapInfo)  // Not used in this example

#define IFXCPU_TRAP_CFG_SYSCALL_CPU3_HOOK(trapInfo)  // Not used in this example

#define IFXCPU_TRAP_CFG_SYSCALL_CPU4_HOOK(trapInfo)  // Not used in this example

#define IFXCPU_TRAP_CFG_SYSCALL_CPU5_HOOK(trapInfo)  // Not used in this example

The exten hooks are effective only if this feature is enabled as explained in Ifx_Trap_Hooks_EnableExtn