iLLD_TC27xC  1.0
IfxCpu_Irq.h
Go to the documentation of this file.
1 /**
2  * \file IfxCpu_Irq.h
3  * \brief This file contains the APIs for Interrupt related functions.
4  *
5  *
6  * \version iLLD_0_1_0_10
7  * \copyright Copyright (c) 2012 Infineon Technologies AG. All rights reserved.
8  *
9  *
10  * IMPORTANT NOTICE
11  *
12  *
13  * Infineon Technologies AG (Infineon) is supplying this file for use
14  * exclusively with Infineon's microcontroller products. This file can be freely
15  * distributed within development tools that are supporting such microcontroller
16  * products.
17  *
18  * THIS SOFTWARE IS PROVIDED "AS IS". NO WARRANTIES, WHETHER EXPRESS, IMPLIED
19  * OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF
20  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE APPLY TO THIS SOFTWARE.
21  * INFINEON SHALL NOT, IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL,
22  * OR CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER.
23  *
24  * \defgroup IfxLld_Cpu_Irq Interrupt Functions
25  * \ingroup IfxLld_Cpu
26  *
27  * \defgroup IfxLld_Cpu_Irq_Usage How to define Interrupts?
28  * \ingroup IfxLld_Cpu_Irq
29  *
30  */
31 #ifndef IFXCPU_IRQ_H_
32 #define IFXCPU_IRQ_H_
33 
34 /*******************************************************************************
35 ** Includes **
36 *******************************************************************************/
37 #include "Ifx_Cfg.h"
38 #include "Cpu/Std/Ifx_Types.h"
39 
40 /*******************************************************************************
41 ** Type definitions **
42 *******************************************************************************/
43 
44 /*******************************************************************************
45 ** Global Exported variables/constants **
46 *******************************************************************************/
47 
48 /*******************************************************************************
49 ** Global Exported macros/inlines/function ptototypes **
50 *******************************************************************************/
51 
52 #if defined(IFX_USE_SW_MANAGED_INT)
53 /** \addtogroup IfxLld_Cpu_Irq_Usage
54  * \{ */
55 /** \brief API for Interrupt handler install for SW Managed interrupts.
56  * This API installs the isr to SW interrupt vector.
57  * This must be used only when IFX_USE_SW_MANAGED_INT is defined in Ifx_Cfg.h
58  *
59  * \param isrFuncPointer pointer to ISR function.
60  * \param serviceReqPrioNumber ISR priority.
61  */
62 
63 IFX_EXTERN void IfxCpu_Irq_installInterruptHandler(void *isrFuncPointer, uint32 serviceReqPrioNumber);
64 
65 IFX_INLINE void interruptHandlerInstall(uint32 srpn, uint32 addr)
66 {
67  IfxCpu_Irq_installInterruptHandler((void *)addr, srpn);
68 }
69 
70 
71 /** \} */
72 #endif /*defined(IFX_USE_SW_MANAGED_INT) */
73 
74 /*Documentation */
75 /** \addtogroup IfxLld_Cpu_Irq_Usage
76  * \{
77  *
78  * This page describes how to use interrupts with application framework.\n
79  *
80  * \section IfxLld_Cpu_Irq_Terminology Interrupts Terminology:
81  * \subsection IfxLld_Cpu_Irq_HWManaged Hardware Managed Interrupt Mechanism.
82  * Hardware managed interrupts have static interrupt vector which are defined for each priority separately.
83  * These vectors have jump instruction to the interrupt handler.
84  *
85  * Advantages:\n
86  * This mechanism has less interrupt latency time.
87  *
88  * \subsection IfxLld_Cpu_Irq_SWManaged Software Managed Interrupt Mechanism.
89  * Software managed interrupts have single interrupt vector statically defined at vector position 255.
90  * This address is assigned to BIV during startup.\n
91  * For Tricore, this vector position is important, because whenever an interrupt occurs, with whichever priority,
92  * the execution control jumps to this vector position. The code at this vector position will:\n
93  * 1) fetch the priority of the targetted interrupt.\n
94  * 2) fetch the interrupt handler defined for this priority (this is done by Interrupt handler installation. Refer
95  * \ref IfxLld_Cpu_Irq_Step4\n
96  * 3) Then call the handler as notmal function call.
97  *
98  * Advantages:\n
99  * This kind of mechanism is useful when project wants to change the handler for an interrupt during runtime.
100  *
101  * Disadvantages:\n
102  * This mechanism has more interrupt latency time.
103  *
104  * of the interrupt and in tand jumps to the function
105  *
106  * \section IfxLld_Cpu_Irq_Steps Steps to use Interrupt Mechanism.
107  * Dependency: Ifx_Compilers, Ifx_Cpu, Ifx_Src, IfxCpu_Irq\n
108  * Following are the steps to use interrupt mechanism.
109  *
110  * \section IfxLld_Cpu_Irq_Step1 Step1: Define Interrupt priorities.
111  * Define priorities of all interrupts with names corresponding to their functionality. It is recommended to define
112  * such priority definitions in single header file, because it is easy to detect if ISR priorities are conflicting.
113  * In Tricore architecture, two Isrs can't have same priority at same point of time.
114  * \note These defines shall be defined without brackets surrounding priority number. (eg. #define PRIO (10) is not allowed)
115  *
116  * In a user defined file eg. Ifx_IntPrioDef.h, placed in folder: 0_AppSw/Tricore/DemoApp:
117  * \code
118  * //file: Ifx_IntPrioDef.h.
119  * #define IFX_INTPRIO_FUNCT1 1
120  * #define IFX_INTPRIO_FUNCT2 2
121  * #define IFX_INTPRIO_FUNCT3 5
122  * #define IFX_INTPRIO_STM0 8
123  * #define IFX_INTPRIO_ADC_FUNC1 10
124  * //etc.
125  * \endcode
126  *
127  * \note !! IMPORTANT !!\n As explained above, the definition with closing bracket around priority number as,
128  * #define IFX_INTPRIO_FUNCT1 (1) will cause compilation error. Because linker sections which are constructed
129  * using such information will also get these brackets included. Which look like ".intvec_tc0_(1)" instead of the
130  * expected ".intvec_tc0_1"\n
131  * Linker sections' definitions are predefined statically in .lsl file,
132  * for all 255 interrupts, with the format ".intvec_tc<vector number>_<interrupt priority>".
133  *
134  * \section IfxLld_Cpu_Irq_Step2 Step2: Define Type of interrupt mechanism.
135  * \subsection IfxLld_Cpu_Irq_HWManaged_Usage To use Hardware Managed Interrupt Mechanism.
136  * Refer \ref IfxLld_Cpu_Irq_HWManaged
137  * If project is designed for hardware managed interrupts, this feature is enabled at the file Ifx_Cfg.h, at path:
138  * 0_Src/0_AppSw/Config/Common/, as shown below. IFX_USE_SW_MANAGED_INT definition must be undefined (i.e. the
139  * statement "#define IFX_USE_SW_MANAGED_INT" shall be commented as below).
140  *
141  * \code
142  * //file: Ifx_Cfg.h
143  *
144  * //#define IFX_USE_SW_MANAGED_INT
145  *
146  * \endcode
147  *
148  * \subsection IfxLld_Cpu_Irq_SWManaged_Usage To use Software Managed Interrupt Mechanism.
149  * Refer \ref IfxLld_Cpu_Irq_SWManaged
150  * If project is designed for software managed interrupts, this feature is enabled at the file Ifx_Cfg.h, at path:
151  * 0_Src/0_AppSw/Config/Common/, as shown below.
152  * IFX_USE_SW_MANAGED_INT definition must be defined.
153  *
154  * \code
155  * //file: Ifx_Cfg.h
156  *
157  * #define IFX_USE_SW_MANAGED_INT
158  *
159  * \endcode
160  *
161  * Software managed interrupts must also install the "Interrupt Handlers" Refer \ref IfxLld_Cpu_Irq_Step4
162  *
163  * \section IfxLld_Cpu_Irq_Step3 Step3: How to define an Interrupt Service routine?
164  * Interrupt service routines or interrupt handlers are defined in driver specific files or application specific
165  * files.
166  *
167  * \code
168  * //file usercode1.c
169  * #include "Compilers.h" // to get the compiler abstracted macros for interrupt definition
170  * #include "Ifx_IntPrioDef.h" // to get the priority numbers
171  *
172  * //define an ISR with name Isr_Stm0 with priority defined by IFX_INTPRIO_STM0
173  * IFX_INTERRUPT (Isr_Stm0, 0, IFX_INTPRIO_STM0)
174  * {
175  * //Isr code here
176  * }
177  * \endcode
178  *
179  * \code
180  * //file usercode2.c
181  * #include "Compilers.h" // to get the compiler abstracted macros for interrupt definition
182  * #include "Ifx_IntPrioDef.h" // to get the priority numbers
183  *
184  * //define an ISR with name Isr_Adc_fun1 with priority defined by IFX_INTPRIO_ADC_FUNC1
185  * IFX_INTERRUPT (Isr_Adc_fun1, 0, IFX_INTPRIO_ADC_FUNC1)
186  * {
187  * //Isr code here
188  * }
189  * \endcode
190  *
191  * \section IfxLld_Cpu_Irq_Step4 Step4: How to install Interrupt Service routine/handler?
192  * This step is not required for HW managed interrupts.\n
193  * Interrupt service routines or interrupt handlers are installed in driver specific files or application specific
194  * files
195  *
196  * \code
197  * //file usermain.c
198  * #include "IfxCpu_Irq.h"
199  * #include "Ifx_IntPrioDef.h" // to get the priority numbers
200  *
201  * void userfunction_init(void)
202  * {
203  * //code for user function init
204  * // :
205  * // :
206  * IfxCpu_Irq_installInterruptHandler (Isr_Stm0, IFX_INTPRIO_STM0);
207  * IfxCpu_Irq_installInterruptHandler (Isr_Adc_fun1, IFX_INTPRIO_ADC_FUNC1);
208  *
209  * // :
210  * }
211  *
212  * \endcode
213  *
214  * \section IfxLld_Cpu_Irq_Step5 Step5: Managing the Service Request Node.
215  * For the interrupt to get activated, interrupt triggers are needed. These triggers are activated by peripheral modules
216  * and corresponding service request node must be\n
217  * 1) Configured with correct priority number\n
218  * 2) The request node must be enabled\n
219  * Refer to \ref IfxLld_Src_Usage
220  */
221 
222 /** \} */
223 #endif /* IFXCPU_IRQ_H_ */