Zephyr API Documentation  2.7.0-rc2
A Scalable Open Source RTOS
Interrupt Service Routine APIs

Macros

#define IRQ_CONNECT(irq_p, priority_p, isr_p, isr_param_p, flags_p)    ARCH_IRQ_CONNECT(irq_p, priority_p, isr_p, isr_param_p, flags_p)
 Initialize an interrupt handler. More...
 
#define IRQ_DIRECT_CONNECT(irq_p, priority_p, isr_p, flags_p)    ARCH_IRQ_DIRECT_CONNECT(irq_p, priority_p, isr_p, flags_p)
 Initialize a 'direct' interrupt handler. More...
 
#define ISR_DIRECT_HEADER()   ARCH_ISR_DIRECT_HEADER()
 Common tasks before executing the body of an ISR. More...
 
#define ISR_DIRECT_FOOTER(check_reschedule)    ARCH_ISR_DIRECT_FOOTER(check_reschedule)
 Common tasks before exiting the body of an ISR. More...
 
#define ISR_DIRECT_PM()   ARCH_ISR_DIRECT_PM()
 Perform power management idle exit logic. More...
 
#define ISR_DIRECT_DECLARE(name)   ARCH_ISR_DIRECT_DECLARE(name)
 Helper macro to declare a direct interrupt service routine. More...
 
#define irq_lock()   z_smp_global_lock()
 Lock interrupts. More...
 
#define irq_unlock(key)   z_smp_global_unlock(key)
 Unlock interrupts. More...
 
#define irq_enable(irq)   arch_irq_enable(irq)
 Enable an IRQ. More...
 
#define irq_disable(irq)   arch_irq_disable(irq)
 Disable an IRQ. More...
 
#define irq_is_enabled(irq)   arch_irq_is_enabled(irq)
 Get IRQ enable state. More...
 

Functions

static int irq_connect_dynamic (unsigned int irq, unsigned int priority, void(*routine)(const void *parameter), const void *parameter, uint32_t flags)
 
static unsigned int irq_get_level (unsigned int irq)
 
bool k_is_in_isr (void)
 Determine if code is running at interrupt level. More...
 
int k_is_preempt_thread (void)
 Determine if code is running in a preemptible thread. More...
 
static bool k_is_pre_kernel (void)
 Test whether startup is in the before-main-task phase. More...
 

Detailed Description

Macro Definition Documentation

◆ IRQ_CONNECT

#define IRQ_CONNECT (   irq_p,
  priority_p,
  isr_p,
  isr_param_p,
  flags_p 
)     ARCH_IRQ_CONNECT(irq_p, priority_p, isr_p, isr_param_p, flags_p)

#include <include/irq.h>

Initialize an interrupt handler.

This routine initializes an interrupt handler for an IRQ. The IRQ must be subsequently enabled before the interrupt handler begins servicing interrupts.

Warning
Although this routine is invoked at run-time, all of its arguments must be computable by the compiler at build time.
Parameters
irq_pIRQ line number.
priority_pInterrupt priority.
isr_pAddress of interrupt service routine.
isr_param_pParameter passed to interrupt service routine.
flags_pArchitecture-specific IRQ configuration flags..

◆ IRQ_DIRECT_CONNECT

#define IRQ_DIRECT_CONNECT (   irq_p,
  priority_p,
  isr_p,
  flags_p 
)     ARCH_IRQ_DIRECT_CONNECT(irq_p, priority_p, isr_p, flags_p)

#include <include/irq.h>

Initialize a 'direct' interrupt handler.

This routine initializes an interrupt handler for an IRQ. The IRQ must be subsequently enabled via irq_enable() before the interrupt handler begins servicing interrupts.

These ISRs are designed for performance-critical interrupt handling and do not go through common interrupt handling code. They must be implemented in such a way that it is safe to put them directly in the vector table. For ISRs written in C, The ISR_DIRECT_DECLARE() macro will do this automatically. For ISRs written in assembly it is entirely up to the developer to ensure that the right steps are taken.

This type of interrupt currently has a few limitations compared to normal Zephyr interrupts:

  • No parameters are passed to the ISR.
  • No stack switch is done, the ISR will run on the interrupted context's stack, unless the architecture automatically does the stack switch in HW.
  • Interrupt locking state is unchanged from how the HW sets it when the ISR runs. On arches that enter ISRs with interrupts locked, they will remain locked.
  • Scheduling decisions are now optional, controlled by the return value of ISRs implemented with the ISR_DIRECT_DECLARE() macro
  • The call into the OS to exit power management idle state is now optional. Normal interrupts always do this before the ISR is run, but when it runs is now controlled by the placement of a ISR_DIRECT_PM() macro, or omitted entirely.
Warning
Although this routine is invoked at run-time, all of its arguments must be computable by the compiler at build time.
Parameters
irq_pIRQ line number.
priority_pInterrupt priority.
isr_pAddress of interrupt service routine.
flags_pArchitecture-specific IRQ configuration flags.

◆ irq_disable

#define irq_disable (   irq)    arch_irq_disable(irq)

#include <include/irq.h>

Disable an IRQ.

This routine disables interrupts from source irq.

Parameters
irqIRQ line.
Returns
N/A

◆ irq_enable

#define irq_enable (   irq)    arch_irq_enable(irq)

#include <include/irq.h>

Enable an IRQ.

This routine enables interrupts from source irq.

Parameters
irqIRQ line.
Returns
N/A

◆ irq_is_enabled

#define irq_is_enabled (   irq)    arch_irq_is_enabled(irq)

#include <include/irq.h>

Get IRQ enable state.

This routine indicates if interrupts from source irq are enabled.

Parameters
irqIRQ line.
Returns
interrupt enable state, true or false

◆ irq_lock

#define irq_lock ( )    z_smp_global_lock()

#include <include/irq.h>

Lock interrupts.

This routine disables all interrupts on the CPU. It returns an unsigned integer "lock-out key", which is an architecture-dependent indicator of whether interrupts were locked prior to the call. The lock-out key must be passed to irq_unlock() to re-enable interrupts.

Note
This routine must also serve as a memory barrier to ensure the uniprocessor implementation of k_spinlock_t is correct.

This routine can be called recursively, as long as the caller keeps track of each lock-out key that is generated. Interrupts are re-enabled by passing each of the keys to irq_unlock() in the reverse order they were acquired. (That is, each call to irq_lock() must be balanced by a corresponding call to irq_unlock().)

This routine can only be invoked from supervisor mode. Some architectures (for example, ARM) will fail silently if invoked from user mode instead of generating an exception.

Note
This routine can be called by ISRs or by threads. If it is called by a thread, the interrupt lock is thread-specific; this means that interrupts remain disabled only while the thread is running. If the thread performs an operation that allows another thread to run (for example, giving a semaphore or sleeping for N milliseconds), the interrupt lock no longer applies and interrupts may be re-enabled while other processing occurs. When the thread once again becomes the current thread, the kernel re-establishes its interrupt lock; this ensures the thread won't be interrupted until it has explicitly released the interrupt lock it established.
Warning
The lock-out key should never be used to manually re-enable interrupts or to inspect or manipulate the contents of the CPU's interrupt bits.
Returns
An architecture-dependent lock-out key representing the "interrupt disable state" prior to the call.

◆ irq_unlock

#define irq_unlock (   key)    z_smp_global_unlock(key)

#include <include/irq.h>

Unlock interrupts.

This routine reverses the effect of a previous call to irq_lock() using the associated lock-out key. The caller must call the routine once for each time it called irq_lock(), supplying the keys in the reverse order they were acquired, before interrupts are enabled.

Note
This routine must also serve as a memory barrier to ensure the uniprocessor implementation of k_spinlock_t is correct.

This routine can only be invoked from supervisor mode. Some architectures (for example, ARM) will fail silently if invoked from user mode instead of generating an exception.

Note
Can be called by ISRs.
Parameters
keyLock-out key generated by irq_lock().
Returns
N/A

◆ ISR_DIRECT_DECLARE

#define ISR_DIRECT_DECLARE (   name)    ARCH_ISR_DIRECT_DECLARE(name)

#include <include/irq.h>

Helper macro to declare a direct interrupt service routine.

This will declare the function in a proper way and automatically include the ISR_DIRECT_FOOTER() and ISR_DIRECT_HEADER() macros. The function should return nonzero status if a scheduling decision should potentially be made. See ISR_DIRECT_FOOTER() for more details on the scheduling decision.

For architectures that support 'regular' and 'fast' interrupt types, where these interrupt types require different assembly language handling of registers by the ISR, this will always generate code for the 'fast' interrupt type.

Example usage:

ISR_DIRECT_DECLARE(my_isr)
{
        bool done = do_stuff();
        ISR_DIRECT_PM(); // done after do_stuff() due to latency concerns
        if (!done) {
            return 0; // don't bother checking if we have to z_swap()
        }

        k_sem_give(some_sem);
        return 1;
 }
Parameters
namesymbol name of the ISR

◆ ISR_DIRECT_FOOTER

#define ISR_DIRECT_FOOTER (   check_reschedule)     ARCH_ISR_DIRECT_FOOTER(check_reschedule)

#include <include/irq.h>

Common tasks before exiting the body of an ISR.

This macro must be at the end of all direct interrupts and performs minimal architecture-specific tasks like EOI. It has no return value.

In a normal interrupt, a check is done at end of interrupt to invoke z_swap() logic if the current thread is preemptible and there is another thread ready to run in the kernel's ready queue cache. This is now optional and controlled by the check_reschedule argument. If unsure, set to nonzero. On systems that do stack switching and nested interrupt tracking in software, z_swap() should only be called if this was a non-nested interrupt.

Parameters
check_rescheduleIf nonzero, additionally invoke scheduling logic

◆ ISR_DIRECT_HEADER

#define ISR_DIRECT_HEADER ( )    ARCH_ISR_DIRECT_HEADER()

#include <include/irq.h>

Common tasks before executing the body of an ISR.

This macro must be at the beginning of all direct interrupts and performs minimal architecture-specific tasks before the ISR itself can run. It takes no arguments and has no return value.

◆ ISR_DIRECT_PM

#define ISR_DIRECT_PM ( )    ARCH_ISR_DIRECT_PM()

#include <include/irq.h>

Perform power management idle exit logic.

This macro may optionally be invoked somewhere in between IRQ_DIRECT_HEADER() and IRQ_DIRECT_FOOTER() invocations. It performs tasks necessary to exit power management idle state. It takes no parameters and returns no arguments. It may be omitted, but be careful!

Function Documentation

◆ irq_connect_dynamic()

static int irq_connect_dynamic ( unsigned int  irq,
unsigned int  priority,
void(*)(const void *parameter)  routine,
const void parameter,
uint32_t  flags 
)
inlinestatic

#include <include/irq.h>

Configure a dynamic interrupt.

Use this instead of IRQ_CONNECT() if arguments cannot be known at build time.

Parameters
irqIRQ line number
priorityInterrupt priority
routineInterrupt service routine
parameterISR parameter
flagsArch-specific IRQ configuration flags
Returns
The vector assigned to this interrupt

◆ irq_get_level()

static unsigned int irq_get_level ( unsigned int  irq)
inlinestatic

#include <include/irq.h>

◆ k_is_in_isr()

bool k_is_in_isr ( void  )

#include <include/kernel.h>

Determine if code is running at interrupt level.

This routine allows the caller to customize its actions, depending on whether it is a thread or an ISR.

Function properties (list may not be complete)
isr-ok
Returns
false if invoked by a thread.
true if invoked by an ISR.

◆ k_is_pre_kernel()

static bool k_is_pre_kernel ( void  )
inlinestatic

#include <include/kernel.h>

Test whether startup is in the before-main-task phase.

This routine allows the caller to customize its actions, depending on whether it being invoked before the kernel is fully active.

Function properties (list may not be complete)
isr-ok
Returns
true if invoked before post-kernel initialization
false if invoked during/after post-kernel initialization

◆ k_is_preempt_thread()

int k_is_preempt_thread ( void  )

#include <include/kernel.h>

Determine if code is running in a preemptible thread.

This routine allows the caller to customize its actions, depending on whether it can be preempted by another thread. The routine returns a 'true' value if all of the following conditions are met:

  • The code is running in a thread, not at ISR.
  • The thread's priority is in the preemptible range.
  • The thread has not locked the scheduler.
Function properties (list may not be complete)
isr-ok
Returns
0 if invoked by an ISR or by a cooperative thread.
Non-zero if invoked by a preemptible thread.