1 /*
2  * Copyright (c) 2015 Intel corporation
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 /**
8  * @file
9  * @brief Public interface for configuring interrupts
10  */
11 #ifndef ZEPHYR_INCLUDE_IRQ_H_
12 #define ZEPHYR_INCLUDE_IRQ_H_
13 
14 /* Pull in the arch-specific implementations */
15 #include <arch/cpu.h>
16 
17 #ifndef _ASMLANGUAGE
18 #include <toolchain.h>
19 #include <zephyr/types.h>
20 
21 #ifdef __cplusplus
22 extern "C" {
23 #endif
24 
25 /**
26  * @defgroup isr_apis Interrupt Service Routine APIs
27  * @ingroup kernel_apis
28  * @{
29  */
30 
31 /**
32  * @brief Initialize an interrupt handler.
33  *
34  * This routine initializes an interrupt handler for an IRQ. The IRQ must be
35  * subsequently enabled before the interrupt handler begins servicing
36  * interrupts.
37  *
38  * @warning
39  * Although this routine is invoked at run-time, all of its arguments must be
40  * computable by the compiler at build time.
41  *
42  * @param irq_p IRQ line number.
43  * @param priority_p Interrupt priority.
44  * @param isr_p Address of interrupt service routine.
45  * @param isr_param_p Parameter passed to interrupt service routine.
46  * @param flags_p Architecture-specific IRQ configuration flags..
47  */
48 #define IRQ_CONNECT(irq_p, priority_p, isr_p, isr_param_p, flags_p) \
49 	ARCH_IRQ_CONNECT(irq_p, priority_p, isr_p, isr_param_p, flags_p)
50 
51 /**
52  * Configure a dynamic interrupt.
53  *
54  * Use this instead of IRQ_CONNECT() if arguments cannot be known at build time.
55  *
56  * @param irq IRQ line number
57  * @param priority Interrupt priority
58  * @param routine Interrupt service routine
59  * @param parameter ISR parameter
60  * @param flags Arch-specific IRQ configuration flags
61  *
62  * @return The vector assigned to this interrupt
63  */
64 static inline int
irq_connect_dynamic(unsigned int irq,unsigned int priority,void (* routine)(const void * parameter),const void * parameter,uint32_t flags)65 irq_connect_dynamic(unsigned int irq, unsigned int priority,
66 		    void (*routine)(const void *parameter),
67 		    const void *parameter, uint32_t flags)
68 {
69 	return arch_irq_connect_dynamic(irq, priority, routine, parameter,
70 					flags);
71 }
72 
73 /**
74  * @brief Initialize a 'direct' interrupt handler.
75  *
76  * This routine initializes an interrupt handler for an IRQ. The IRQ must be
77  * subsequently enabled via irq_enable() before the interrupt handler begins
78  * servicing interrupts.
79  *
80  * These ISRs are designed for performance-critical interrupt handling and do
81  * not go through common interrupt handling code. They must be implemented in
82  * such a way that it is safe to put them directly in the vector table.  For
83  * ISRs written in C, The ISR_DIRECT_DECLARE() macro will do this
84  * automatically. For ISRs written in assembly it is entirely up to the
85  * developer to ensure that the right steps are taken.
86  *
87  * This type of interrupt currently has a few limitations compared to normal
88  * Zephyr interrupts:
89  * - No parameters are passed to the ISR.
90  * - No stack switch is done, the ISR will run on the interrupted context's
91  *   stack, unless the architecture automatically does the stack switch in HW.
92  * - Interrupt locking state is unchanged from how the HW sets it when the ISR
93  *   runs. On arches that enter ISRs with interrupts locked, they will remain
94  *   locked.
95  * - Scheduling decisions are now optional, controlled by the return value of
96  *   ISRs implemented with the ISR_DIRECT_DECLARE() macro
97  * - The call into the OS to exit power management idle state is now optional.
98  *   Normal interrupts always do this before the ISR is run, but when it runs
99  *   is now controlled by the placement of a ISR_DIRECT_PM() macro, or omitted
100  *   entirely.
101  *
102  * @warning
103  * Although this routine is invoked at run-time, all of its arguments must be
104  * computable by the compiler at build time.
105  *
106  * @param irq_p IRQ line number.
107  * @param priority_p Interrupt priority.
108  * @param isr_p Address of interrupt service routine.
109  * @param flags_p Architecture-specific IRQ configuration flags.
110  */
111 #define IRQ_DIRECT_CONNECT(irq_p, priority_p, isr_p, flags_p) \
112 	ARCH_IRQ_DIRECT_CONNECT(irq_p, priority_p, isr_p, flags_p)
113 
114 /**
115  * @brief Common tasks before executing the body of an ISR
116  *
117  * This macro must be at the beginning of all direct interrupts and performs
118  * minimal architecture-specific tasks before the ISR itself can run. It takes
119  * no arguments and has no return value.
120  */
121 #define ISR_DIRECT_HEADER() ARCH_ISR_DIRECT_HEADER()
122 
123 /**
124  * @brief Common tasks before exiting the body of an ISR
125  *
126  * This macro must be at the end of all direct interrupts and performs
127  * minimal architecture-specific tasks like EOI. It has no return value.
128  *
129  * In a normal interrupt, a check is done at end of interrupt to invoke
130  * z_swap() logic if the current thread is preemptible and there is another
131  * thread ready to run in the kernel's ready queue cache. This is now optional
132  * and controlled by the check_reschedule argument. If unsure, set to nonzero.
133  * On systems that do stack switching and nested interrupt tracking in software,
134  * z_swap() should only be called if this was a non-nested interrupt.
135  *
136  * @param check_reschedule If nonzero, additionally invoke scheduling logic
137  */
138 #define ISR_DIRECT_FOOTER(check_reschedule) \
139 	ARCH_ISR_DIRECT_FOOTER(check_reschedule)
140 
141 /**
142  * @brief Perform power management idle exit logic
143  *
144  * This macro may optionally be invoked somewhere in between IRQ_DIRECT_HEADER()
145  * and IRQ_DIRECT_FOOTER() invocations. It performs tasks necessary to
146  * exit power management idle state. It takes no parameters and returns no
147  * arguments. It may be omitted, but be careful!
148  */
149 #define ISR_DIRECT_PM() ARCH_ISR_DIRECT_PM()
150 
151 /**
152  * @brief Helper macro to declare a direct interrupt service routine.
153  *
154  * This will declare the function in a proper way and automatically include
155  * the ISR_DIRECT_FOOTER() and ISR_DIRECT_HEADER() macros. The function should
156  * return nonzero status if a scheduling decision should potentially be made.
157  * See ISR_DIRECT_FOOTER() for more details on the scheduling decision.
158  *
159  * For architectures that support 'regular' and 'fast' interrupt types, where
160  * these interrupt types require different assembly language handling of
161  * registers by the ISR, this will always generate code for the 'fast'
162  * interrupt type.
163  *
164  * Example usage:
165  *
166  *     ISR_DIRECT_DECLARE(my_isr)
167  *     {
168  *             bool done = do_stuff();
169  *             ISR_DIRECT_PM(); // done after do_stuff() due to latency concerns
170  *             if (!done) {
171  *                 return 0; // don't bother checking if we have to z_swap()
172  *             }
173  *
174  *             k_sem_give(some_sem);
175  *             return 1;
176  *      }
177  *
178  * @param name symbol name of the ISR
179  */
180 #define ISR_DIRECT_DECLARE(name) ARCH_ISR_DIRECT_DECLARE(name)
181 
182 /**
183  * @brief Lock interrupts.
184  * @def irq_lock()
185  *
186  * This routine disables all interrupts on the CPU. It returns an unsigned
187  * integer "lock-out key", which is an architecture-dependent indicator of
188  * whether interrupts were locked prior to the call. The lock-out key must be
189  * passed to irq_unlock() to re-enable interrupts.
190  *
191  * @note
192  * This routine must also serve as a memory barrier to ensure the uniprocessor
193  * implementation of `k_spinlock_t` is correct.
194  *
195  * This routine can be called recursively, as long as the caller keeps track
196  * of each lock-out key that is generated. Interrupts are re-enabled by
197  * passing each of the keys to irq_unlock() in the reverse order they were
198  * acquired. (That is, each call to irq_lock() must be balanced by
199  * a corresponding call to irq_unlock().)
200  *
201  * This routine can only be invoked from supervisor mode. Some architectures
202  * (for example, ARM) will fail silently if invoked from user mode instead
203  * of generating an exception.
204  *
205  * @note
206  * This routine can be called by ISRs or by threads. If it is called by a
207  * thread, the interrupt lock is thread-specific; this means that interrupts
208  * remain disabled only while the thread is running. If the thread performs an
209  * operation that allows another thread to run (for example, giving a semaphore
210  * or sleeping for N milliseconds), the interrupt lock no longer applies and
211  * interrupts may be re-enabled while other processing occurs. When the thread
212  * once again becomes the current thread, the kernel re-establishes its
213  * interrupt lock; this ensures the thread won't be interrupted until it has
214  * explicitly released the interrupt lock it established.
215  *
216  * @warning
217  * The lock-out key should never be used to manually re-enable interrupts
218  * or to inspect or manipulate the contents of the CPU's interrupt bits.
219  *
220  * @return An architecture-dependent lock-out key representing the
221  *         "interrupt disable state" prior to the call.
222  */
223 #ifdef CONFIG_SMP
224 unsigned int z_smp_global_lock(void);
225 #define irq_lock() z_smp_global_lock()
226 #else
227 #define irq_lock() arch_irq_lock()
228 #endif
229 
230 /**
231  * @brief Unlock interrupts.
232  * @def irq_unlock()
233  *
234  * This routine reverses the effect of a previous call to irq_lock() using
235  * the associated lock-out key. The caller must call the routine once for
236  * each time it called irq_lock(), supplying the keys in the reverse order
237  * they were acquired, before interrupts are enabled.
238  *
239  * @note
240  * This routine must also serve as a memory barrier to ensure the uniprocessor
241  * implementation of `k_spinlock_t` is correct.
242  *
243  * This routine can only be invoked from supervisor mode. Some architectures
244  * (for example, ARM) will fail silently if invoked from user mode instead
245  * of generating an exception.
246  *
247  * @note Can be called by ISRs.
248  *
249  * @param key Lock-out key generated by irq_lock().
250  *
251  * @return N/A
252  */
253 #ifdef CONFIG_SMP
254 void z_smp_global_unlock(unsigned int key);
255 #define irq_unlock(key) z_smp_global_unlock(key)
256 #else
257 #define irq_unlock(key) arch_irq_unlock(key)
258 #endif
259 
260 /**
261  * @brief Return IRQ level
262  * @def irq_get_level()
263  *
264  * This routine returns the interrupt level number of the provided interrupt.
265  *
266  * @param irq IRQ number in its zephyr format
267  *
268  * @return 1 if IRQ level 1, 2 if IRQ level 2, 3 if IRQ level 3
269  */
irq_get_level(unsigned int irq)270 static inline unsigned int irq_get_level(unsigned int irq)
271 {
272 #if defined(CONFIG_3RD_LEVEL_INTERRUPTS)
273 	return ((irq >> 16) & 0xFF) != 0 ? 3 :
274 		(((irq >> 8) & 0xFF) == 0 ? 1 : 2);
275 #elif defined(CONFIG_2ND_LEVEL_INTERRUPTS)
276 	return ((irq >> 8) & 0xFF) == 0 ? 1 : 2;
277 #else
278 	ARG_UNUSED(irq);
279 
280 	return 1;
281 #endif
282 }
283 
284 #ifdef CONFIG_2ND_LEVEL_INTERRUPTS
285 /**
286  * @brief Return the 2nd level interrupt number
287  * @def irq_from_level_2()
288  *
289  * This routine returns the second level irq number of the zephyr irq
290  * number passed in
291  *
292  * @param irq IRQ number in its zephyr format
293  *
294  * @return 2nd level IRQ number
295  */
irq_from_level_2(unsigned int irq)296 static inline unsigned int irq_from_level_2(unsigned int irq)
297 {
298 #ifdef CONFIG_3RD_LEVEL_INTERRUPTS
299 	return ((irq >> 8) & 0xFF) - 1;
300 #else
301 	return (irq >> 8) - 1;
302 #endif
303 }
304 
305 /**
306  * @brief Converts irq from level 1 to level 2 format
307  * @def irq_to_level_2()
308  *
309  * This routine converts the input into the level 2 irq number format
310  *
311  * @note Values >= 0xFF are invalid
312  *
313  * @param irq IRQ number in its zephyr format
314  *
315  * @return 2nd level IRQ number
316  */
irq_to_level_2(unsigned int irq)317 static inline unsigned int irq_to_level_2(unsigned int irq)
318 {
319 	return (irq + 1) << 8;
320 }
321 
322 /**
323  * @brief Returns the parent IRQ of the level 2 raw IRQ number
324  * @def irq_parent_level_2()
325  *
326  * The parent of a 2nd level interrupt is in the 1st byte
327  *
328  * @param irq IRQ number in its zephyr format
329  *
330  * @return 2nd level IRQ parent
331  */
irq_parent_level_2(unsigned int irq)332 static inline unsigned int irq_parent_level_2(unsigned int irq)
333 {
334 	return irq & 0xFF;
335 }
336 #endif
337 
338 #ifdef CONFIG_3RD_LEVEL_INTERRUPTS
339 /**
340  * @brief Return the 3rd level interrupt number
341  * @def irq_from_level_3()
342  *
343  * This routine returns the third level irq number of the zephyr irq
344  * number passed in
345  *
346  * @param irq IRQ number in its zephyr format
347  *
348  * @return 3rd level IRQ number
349  */
irq_from_level_3(unsigned int irq)350 static inline unsigned int irq_from_level_3(unsigned int irq)
351 {
352 	return (irq >> 16) - 1;
353 }
354 
355 /**
356  * @brief Converts irq from level 1 to level 3 format
357  * @def irq_to_level_3()
358  *
359  * This routine converts the input into the level 3 irq number format
360  *
361  * @note Values >= 0xFF are invalid
362  *
363  * @param irq IRQ number in its zephyr format
364  *
365  * @return 3rd level IRQ number
366  */
irq_to_level_3(unsigned int irq)367 static inline unsigned int irq_to_level_3(unsigned int irq)
368 {
369 	return (irq + 1) << 16;
370 }
371 
372 /**
373  * @brief Returns the parent IRQ of the level 3 raw IRQ number
374  * @def irq_parent_level_3()
375  *
376  * The parent of a 3rd level interrupt is in the 2nd byte
377  *
378  * @param irq IRQ number in its zephyr format
379  *
380  * @return 3rd level IRQ parent
381  */
irq_parent_level_3(unsigned int irq)382 static inline unsigned int irq_parent_level_3(unsigned int irq)
383 {
384 	return (irq >> 8) & 0xFF;
385 }
386 #endif
387 
388 /**
389  * @brief Enable an IRQ.
390  *
391  * This routine enables interrupts from source @a irq.
392  *
393  * @param irq IRQ line.
394  *
395  * @return N/A
396  */
397 #define irq_enable(irq) arch_irq_enable(irq)
398 
399 /**
400  * @brief Disable an IRQ.
401  *
402  * This routine disables interrupts from source @a irq.
403  *
404  * @param irq IRQ line.
405  *
406  * @return N/A
407  */
408 #define irq_disable(irq) arch_irq_disable(irq)
409 
410 /**
411  * @brief Get IRQ enable state.
412  *
413  * This routine indicates if interrupts from source @a irq are enabled.
414  *
415  * @param irq IRQ line.
416  *
417  * @return interrupt enable state, true or false
418  */
419 #define irq_is_enabled(irq) arch_irq_is_enabled(irq)
420 
421 /**
422  * @}
423  */
424 
425 #ifdef __cplusplus
426 }
427 #endif
428 
429 #endif /* ASMLANGUAGE */
430 #endif /* ZEPHYR_INCLUDE_IRQ_H_ */
431