iLLD_TC27xC  1.0
IfxCpu_Trap.h
Go to the documentation of this file.
1 /**
2  * \file IfxCpu_Trap.c
3  * \brief This file contains the APIs for Trap related functions.
4  *
5  * \version iLLD_0_1_0_10
6  * \copyright Copyright (c) 2012 Infineon Technologies AG. All rights reserved.
7  *
8  *
9  * IMPORTANT NOTICE
10  *
11  *
12  * Infineon Technologies AG (Infineon) is supplying this file for use
13  * exclusively with Infineon's microcontroller products. This file can be freely
14  * distributed within development tools that are supporting such microcontroller
15  * products.
16  *
17  * THIS SOFTWARE IS PROVIDED "AS IS". NO WARRANTIES, WHETHER EXPRESS, IMPLIED
18  * OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF
19  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE APPLY TO THIS SOFTWARE.
20  * INFINEON SHALL NOT, IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL,
21  * OR CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER.
22  *
23  *
24  * \defgroup IfxLld_Cpu_Trap Trap Functions
25  * \ingroup IfxLld_Cpu
26  *
27  * \defgroup IfxLld_Cpu_Trap_Hooks Trap Function Hooks
28  * \ingroup IfxLld_Cpu_Trap
29  *
30  * \defgroup IfxLld_Cpu_Trap_Usage How to use the Trap Function Hooks?
31  * \ingroup IfxLld_Cpu_Trap
32  *
33  */
34 
35 #ifndef IFXCPU_TRAPS_H_
36 #define IFXCPU_TRAPS_H_
37 
38 /*******************************************************************************
39 ** Includes **
40 *******************************************************************************/
41 #include "Cpu/Std/Ifx_Types.h"
43 #include "Ifx_Cfg.h"
44 
45 /*******************************************************************************
46 ** Type definitions **
47 *******************************************************************************/
48 /** \addtogroup IfxLld_Cpu_Trap_Hooks
49  * \{ */
50 
51 /** \brief Enum for available Trap classes.
52  *
53  */
54 typedef enum
55 {
65 
66 /** \brief Enum for available Identification numbers under Memory Management Trap.
67  *
68  */
69 typedef enum
70 {
74 
75 /** \brief Enum for available Identification numbers under Internal Protection Trap.
76  *
77  */
78 typedef enum
79 {
88 
89 /** \brief Enum for available Identification numbers under Instruction Errors Trap.
90  *
91  */
92 typedef enum
93 {
100 
101 /** \brief Enum for available Identification numbers under Context Management Trap.
102  *
103  */
104 typedef enum
105 {
114 
115 /** \brief Enum for available Identification numbers under Bus Trap.
116  *
117  */
118 typedef enum
119 {
128 
129 /** \brief Enum for available Identification numbers under Assertion Trap.
130  *
131  */
132 typedef enum
133 {
137 
138 /** \brief Type for Identification numbers under SystemCall Trap.
139  *
140  */
142 
143 /** \brief Type for Identification number for Non Maskable Interrupt Trap.
144  *
145  */
147 
148 /** \brief Union to abstract Identification numbers under Traps.
149  *
150  */
151 typedef union
152 {
162 
163 /** \brief Structure to contain the trap information.
164  *
165  */
166 typedef struct
167 {
168  unsigned int tId : 8;
169  unsigned int tClass : 8;
170  unsigned int tCpu : 3;
171 } IfxCpu_Trap;
172 
173 /*******************************************************************************
174 ** Global Exported variables/constants **
175 *******************************************************************************/
176 
177 /*******************************************************************************
178 ** Global Exported macros/inlines/function ptototypes **
179 *******************************************************************************/
180 /** \brief Macro to define the trap vector table.
181  * This macro is provided to define the trap vector table in the frameowrk. User shall not use
182  * this macro.
183  * Refer to the documentation to extend the trap with hook functions. \ref IfxLld_Cpu_Trap_Usage
184  */
185 #if defined(__GNUC__)
186 #define __ALIGN_TRAP_TAB__ __asm(" .align 5");
187 #define IfxCpu_Tsr_CallTSR(serviceRoutine) \
188  { \
189  __ALIGN_TRAP_TAB__; \
190  __asm("mov\t %d4, %d15"); \
191  __asm("ji\t %0" : : "a" (serviceRoutine)); \
192  __asm("rfe"); \
193  }
194 #elif defined(__DCC__)
195 #define IfxCpu_Tsr_CallTSR(serviceRoutine) \
196  { \
197  __ALIGN_TRAP_TAB__; \
198  __asm("\n#$$bp\n"); \
199  __asm(" movh.a\t %a15,"#serviceRoutine "@ha\n"); \
200  __asm(" lea\t %a15,[%a15]"#serviceRoutine "@l\n"); \
201  __asm(" mov\t %d4,%d15\n"); \
202  __asm(" ji\t %a15\n"); \
203  __asm(" rfe"); \
204  __asm("#$$ep"); \
205  }
206 #define __ALIGN_TRAP_TAB__ __asm(" .align 5");
207 #elif defined(__TASKING__)
208 #define IfxCpu_Tsr_CallTSR(serviceRoutine) \
209  { \
210  __ALIGN_TRAP_TAB__; \
211  __asm("mov\td4,d15\n\tji\t%0\n\trfe\n" : : "a" (serviceRoutine) : "d4", "d15"); \
212  }
213 #define __ALIGN_TRAP_TAB__ __asm(" .align 32");
214 #endif
215 
216 /** \} */
217 
218 /*Documentation */
219 /** \addtogroup IfxLld_Cpu_Trap_Usage
220  * \{
221  *
222  * This page describes how to use the trap function hooks with application framework.\n
223  * Framework has built in Trap Service Routines, which has minimal set of debug information.
224  * The execution of trap service is as below,\n
225  * 1) When a trap occurs, a global structure variable "trapWatch" is updated with the information:\n
226  * __a. Which CPU caused this trap,\n
227  * __b. What is the trap class and\n
228  * __c. What is the trap identification number\n
229  * 2) Call to a configurable hook function, passing structure trapWatch as parameter.\n
230  * 3) Then debug instruction executed.\n
231  * 4) Returning from the trap. (This instruction is not reached if debugger is connected because of
232  * "debug" instruction before)\n
233  * For normal cases during development, where user works with debugger, user can watch the structure variable
234  * "trapWatch" in the debugger.
235  *
236  * In case, user wants to make use of the information of trap for further processing,\n
237  * extend the traps, using the hook functions provided.
238  *
239  * \section IfxLld_Cpu_Trap_Hooks Extending the traps with hook functions.
240  *
241  * If the trap extensions are to be extended, it is very important to enable this feature. By default this
242  * feature is disabled.
243  *
244  * \subsection IfxLld_Cpu_Trap_Hooks_EnableExtn How to enable the trap extension feature?
245  * To extend the trap hook functions user must enable this feature by defining the macro
246  * "IFX_CFG_EXTEND_TRAP_HOOKS" in Ifx_Cfg.h, at path: 0_Src/0_AppSw/Config/Common/, as shown below.
247  * \code
248  * //file: Ifx_Cfg.h
249  *
250  * #define IFX_CFG_EXTEND_TRAP_HOOKS
251  *
252  * \endcode
253  * Now the compiler will accept the further configurations to extend the hooks.\n
254  * IfxCpu_Traps_Cfg.h file shall be used to extend the traps. This provide two kind of hook functions.
255  * ie. Hook for error traps and hooks (per CPU available) for system calls.
256  *
257  * \subsection IfxLld_Cpu_Trap_ErrorHooks Extending the "Error traps" with hook function.
258  * Error trap occurs as a result of an error event such as an instruction error, memory-management error
259  * or an illegal access.\n
260  * To extend the error traps, following steps are to be followed:\n
261  * \subsubsection IfxLld_Cpu_Trap_ErrorHooksStep1 Step1: Define a routine to substitute the hook for error traps.
262  * This definition shall be as user defined code (Generally in DemoApps folder).\n
263  * Considerations:\n
264  * 1. Format: IFX_INLINE void <trap extension name>(IfxCpu_Trap trapInfo)
265  * \note Define such a routine with the consideration that the trap extension hook is not a function. In case
266  * of context management error, this extension itself will not call any other function.
267  *
268  * 2. Use the information trapInfo, which is available as parameter passed to this hook and process further.
269  * Example code in a user defined file eg. Ifx_TrapExtension.h, placed under folder/subfolder: 0_AppSw/Tricore/DemoApp:
270  * \code
271  * //Example "inlined" function for trap Extension Hook.
272  * IFX_INLINE myTrapExtensionHook(IfxCpu_Trap trapInfo)
273  * {
274  * switch (trapInfo.tClass)
275  * {
276  * case IfxCpu_Trap_Class_memoryManagement:
277  * {
278  * //user code: Function calls allowed.
279  * break;
280  * }
281  * case IfxCpu_Trap_Class_internalProtection:
282  * {
283  * //user code: Function calls allowed.
284  * break;
285  * }
286  * case IfxCpu_Trap_Class_instructionErrors:
287  * {
288  * //user code: Function calls allowed.
289  * break;
290  * }
291  * case IfxCpu_Trap_Class_contextManagement:
292  * {
293  * //user code: Function calls NOT allowed.
294  * break;
295  * }
296  * case IfxCpu_Trap_Class_bus:
297  * {
298  * //user code: Function calls allowed.
299  * break;
300  * }
301  * case IfxCpu_Trap_Class_assertion:
302  * {
303  * //user code: Function calls allowed.
304  * break;
305  * }
306  * case IfxCpu_Trap_Class_nonMaskableInterrupt:
307  * {
308  * //user code: Function calls allowed.
309  * break;
310  * }
311  * case default:
312  * {
313  * break;
314  * }
315  * }
316  * }
317  * \endcode
318  * \note The error trap functions execute the debug instruction immediately after returning from extension hooks.
319  *
320  * \subsubsection IfxLld_Cpu_Trap_ErrorHooksStep2 Step2: Configure error trap hook extension function.
321  * Configure error trap hook extension function as defined above to the macro as below:
322  * \note Configuration of hook extension is available in IfxCpu_Trap_Cfg at path ../0_Src/0_AppSw/Tricore/McHalCfg/
323  *
324  * \code
325  * //file: IfxCpu_Trap_Cfg.h
326  *
327  * #include "Ifx_TrapExtension.h" //Assuming this is the file name as in above example
328  *
329  * #define IFXCPU_TRAP_CFG_TSR_HOOK(trapInfo) myTrapExtensionHook(trapInfo) //This is INLINE function.
330  *
331  * \endcode
332  * \note The exten hooks are effective only if this feature is enabled as explained in \ref Ifx_Trap_Hooks_EnableExtn
333  *
334  * \subsection IfxLld_Cpu_Trap_SysCallHooks Extending the cpu specific "system call" hook functions.
335  * Tricore architecture provides the system call trap which is executed by software trigger. The instruction "syscall"
336  * triggers this trap. Please refer Tricore architecture manual for more details.\n
337  * IfxCpu_trap driver provide hook function for each CPU separately. To extend System Call trap following steps
338  * are to be followed:\n
339  * \subsubsection IfxLld_Cpu_Trap_SysCallHooksStep1 Step1: Define routine/s to substitute the hook/s for System Call trap.
340  * This definition shall be as user defined code (Generally in DemoApps folder).\n
341  * Considerations:\n
342  * 1. Format: void <syscall function name>(IfxCpu_Trap trapInfo)
343  * It is allowed to define this trap extension as function definition, because this trap is not triggered due to any error.
344  * Depending on the application requirement, define single or per CPU instance of the extension.
345  *
346  * 2. Use the information trapInfo which is available as parameter passed to this hook and process further. The parameter
347  * passed, with syscall instruction, will be trap identification number (refer to Tricore architecture manual for more details).
348  * \note To hook extension, information about trap identification number is available through parameter "trapInfo".
349  *
350  * Example code in a user defined file eg. Ifx_TrapExtension.h, placed under folder/subfolder: 0_AppSw/Tricore/DemoApp:
351  * \code
352  * //Example function for System Call Extension Hook.
353  * IFX_INLINE mySysCallExtensionHook(IfxCpu_Trap trapInfo)
354  * {
355  * switch (trapInfo.tId)
356  * {
357  * case 0:
358  * {
359  * //user code: Function calls allowed.
360  * break;
361  * }
362  * case 1:
363  * {
364  * //user code: Function calls allowed.
365  * break;
366  * }
367  * // and so on..
368  * case default:
369  * {
370  * break;
371  * }
372  * }
373  * }
374  * \endcode
375  *
376  * \subsubsection IfxLld_Cpu_Trap_SysCallHooksStep2 Step2: Configure the extension function.\n
377  * Configure the hook extension function defined above, to the macro as below:
378  * \note Configuration of hook extension is available in IfxCpu_Trap_Cfg file at path ../0_Src/0_AppSw/Tricore/McHalCfg/
379  * \code
380  * //file: IfxCpu_Trap_Cfg.h
381  *
382  * #include "Ifx_TrapExtension.h" //Assuming this is the file name as in above example
383  *
384  * #define IFXCPU_TRAP_CFG_SYSCALL_CPU0_HOOK(trapInfo) mySysCallExtensionHook(trapInfo)
385  *
386  * #define IFXCPU_TRAP_CFG_SYSCALL_CPU1_HOOK(trapInfo) // Not used in this example
387  *
388  * #define IFXCPU_TRAP_CFG_SYSCALL_CPU2_HOOK(trapInfo) // Not used in this example
389  *
390  * \endcode
391  *
392  * \note The exten hooks are effective only if this feature is enabled as explained in \ref Ifx_Trap_Hooks_EnableExtn
393  *
394  */
395 /** \} */
396 
397 #endif /* IFXCPU_TRAPS_H_ */