Interrupt Service Routine APIs

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

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

Detailed Description

Macro Definition Documentation

IRQ_CONNECT

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

#include <zephyr/irq.h>

Value:

        ARCH_IRQ_CONNECT(irq_p, priority_p, isr_p, isr_param_p, flags_p)

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_p	IRQ line number.
priority_p	Interrupt priority.
isr_p	Address of interrupt service routine.
isr_param_p	Parameter passed to interrupt service routine.
flags_p	Architecture-specific IRQ configuration flags..

IRQ_DIRECT_CONNECT

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

#include <zephyr/irq.h>

Value:

        ARCH_IRQ_DIRECT_CONNECT(irq_p, priority_p, isr_p, flags_p)

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_p	IRQ line number.
priority_p	Interrupt priority.
isr_p	Address of interrupt service routine.
flags_p	Architecture-specific IRQ configuration flags.

irq_disable

#define irq_disable

(

irq

)

#include <zephyr/irq.h>

Value:

arch_irq_disable(irq)

Disable an IRQ.

This routine disables interrupts from source irq.

Parameters

irq

IRQ line.

irq_enable

#define irq_enable

(

irq

)

#include <zephyr/irq.h>

Value:

arch_irq_enable(irq)

Enable an IRQ.

This routine enables interrupts from source irq.

Parameters

irq

IRQ line.

irq_is_enabled

#define irq_is_enabled

(

irq

)

#include <zephyr/irq.h>

Value:

arch_irq_is_enabled(irq)

Get IRQ enable state.

This routine indicates if interrupts from source irq are enabled.

Parameters

irq

IRQ line.

Returns

interrupt enable state, true or false

irq_lock

#define irq_lock

(

)

#include <zephyr/irq.h>

Value:

z_smp_global_lock()

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 spinlocks 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

)

#include <zephyr/irq.h>

Value:

z_smp_global_unlock(key)

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 spinlocks 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

key	Lock-out key generated by irq_lock().

ISR_DIRECT_DECLARE

#define ISR_DIRECT_DECLARE

(

name

)

#include <zephyr/irq.h>

Value:

ARCH_ISR_DIRECT_DECLARE(name)

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

name	symbol name of the ISR

ISR_DIRECT_FOOTER

#define ISR_DIRECT_FOOTER

(

check_reschedule

)

#include <zephyr/irq.h>

Value:

        ARCH_ISR_DIRECT_FOOTER(check_reschedule)

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_reschedule

If nonzero, additionally invoke scheduling logic

ISR_DIRECT_HEADER

#define ISR_DIRECT_HEADER

(

)

#include <zephyr/irq.h>

Value:

ARCH_ISR_DIRECT_HEADER()

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

(

)

#include <zephyr/irq.h>

Value:

ARCH_ISR_DIRECT_PM()

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(* routine )(const void *parameter), const void * parameter, uint32_t flags )

inlinestatic

#include <zephyr/irq.h>

Configure a dynamic interrupt.

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

Parameters

irq	IRQ line number
priority	Interrupt priority
routine	Interrupt service routine
parameter	ISR parameter
flags	Arch-specific IRQ configuration flags

Returns

The vector assigned to this interrupt

irq_disconnect_dynamic()

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

inlinestatic

#include <zephyr/irq.h>

Disconnect a dynamic interrupt.

Use this in conjunction with shared interrupts to remove a routine/parameter pair from the list of clients using the same interrupt line. If the interrupt is not being shared then the associated _sw_isr_table entry will be replaced by (NULL, z_irq_spurious) (default entry).

Parameters

irq	IRQ line number
priority	Interrupt priority
routine	Interrupt service routine
parameter	ISR parameter
flags	Arch-specific IRQ configuration flags

Returns

0 in case of success, negative value otherwise

k_is_in_isr()

bool k_is_in_isr ( void )

isr-ok

#include <zephyr/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)

Returns

false if invoked by a thread.

true if invoked by an ISR.

k_is_pre_kernel()

static bool k_is_pre_kernel ( void )

inlinestaticisr-ok

#include <zephyr/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)

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 )

isr-ok

#include <zephyr/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)

Returns

0 if invoked by an ISR or by a cooperative thread.

Non-zero if invoked by a preemptible thread.