Interrupt management.
[Xenomai nucleus.]

Collaboration diagram for Interrupt management.:

---

Detailed Description

Interrupt management.

Files
file	intr.c
	Interrupt management.
Functions
int	xnintr_init (xnintr_t *intr, const char *name, unsigned irq, xnisr_t isr, xniack_t iack, xnflags_t flags)
	Initialize an interrupt object.
int	xnintr_destroy (xnintr_t *intr)
	Destroy an interrupt object.
int	xnintr_attach (xnintr_t *intr, void *cookie)
	Attach an interrupt object.
int	xnintr_detach (xnintr_t *intr)
	Detach an interrupt object.
int	xnintr_enable (xnintr_t *intr)
	Enable an interrupt object.
int	xnintr_disable (xnintr_t *intr)
	Disable an interrupt object.
xnarch_cpumask_t	xnintr_affinity (xnintr_t *intr, xnarch_cpumask_t cpumask)
	Set interrupt's processor affinity.

---

Function Documentation

xnarch_cpumask_t xnintr_affinity	(	xnintr_t *	intr,
		xnarch_cpumask_t	cpumask
	)

Set interrupt's processor affinity.

Causes the IRQ associated with the interrupt object intr to be received only on processors which bits are set in cpumask.

Parameters:

	intr	The descriptor address of the interrupt object which affinity is to be changed.
	cpumask	The new processor affinity of the interrupt object.

Returns:

the previous cpumask on success, or an empty mask on failure.

Note:

Depending on architectures, setting more than one bit in cpumask could be meaningless.

int xnintr_attach	(	xnintr_t *	intr,
		void *	cookie
	)

Attach an interrupt object.

Attach an interrupt object previously initialized by xnintr_init(). After this operation is completed, all IRQs received from the corresponding interrupt channel are directed to the object's ISR.

Parameters:

	intr	The descriptor address of the interrupt object to attach.
	cookie	A user-defined opaque value which is stored into the interrupt object descriptor for further retrieval by the ISR/ISR handlers.

Returns:

0 is returned on success. Otherwise, -EINVAL is returned if a low-level error occurred while attaching the interrupt. -EBUSY is specifically returned if the interrupt object was already attached.

Note:

The caller must not hold nklock when invoking this service, this would cause deadlocks.

Environments:

This service can be called from:

• Kernel module initialization/cleanup code
• Kernel-based task
• User-space task

Rescheduling: never.

Note:

Attaching an interrupt resets the tracked number of receipts to zero.

int xnintr_destroy

(

xnintr_t *

intr

)

Destroy an interrupt object.

Destroys an interrupt object previously initialized by xnintr_init(). The interrupt object is automatically detached by a call to xnintr_detach(). No more IRQs will be dispatched by this object after this service has returned.

Parameters:

intr

The descriptor address of the interrupt object to destroy.

Returns:

0 is returned on success. Otherwise, -EBUSY is returned if an error occurred while detaching the interrupt (see xnintr_detach()).

Environments:

This service can be called from:

• Kernel module initialization/cleanup code
• Kernel-based task
• User-space task

Rescheduling: never.

int xnintr_detach

(

xnintr_t *

intr

)

Detach an interrupt object.

Detach an interrupt object previously attached by xnintr_attach(). After this operation is completed, no more IRQs are directed to the object's ISR, but the interrupt object itself remains valid. A detached interrupt object can be attached again by a subsequent call to xnintr_attach().

Parameters:

intr

The descriptor address of the interrupt object to detach.

Returns:

0 is returned on success. Otherwise, -EINVAL is returned if a low-level error occurred while detaching the interrupt. Detaching a non-attached interrupt object leads to a null-effect and returns 0.

Note:

The caller must not hold nklock when invoking this service, this would cause deadlocks.

Environments:

This service can be called from:

• Kernel module initialization/cleanup code
• Kernel-based task
• User-space task

Rescheduling: never.

int xnintr_disable

(

xnintr_t *

intr

)

Disable an interrupt object.

Disables the hardware interrupt line associated with an interrupt object. This operation invalidates further interrupt requests from the given source until the IRQ line is re-enabled anew.

Parameters:

intr

The descriptor address of the interrupt object to disable.

Returns:

0 is returned on success. Otherwise, -EINVAL is returned if a low-level error occurred while disabling the interrupt.

Environments:

This service can be called from:

• Kernel module initialization/cleanup code
• Kernel-based task
• User-space task

Rescheduling: never.

int xnintr_enable

(

xnintr_t *

intr

)

Enable an interrupt object.

Enables the hardware interrupt line associated with an interrupt object. Over real-time control layers which mask and acknowledge IRQs, this operation is necessary to revalidate the interrupt channel so that more interrupts can be notified.

Parameters:

intr

The descriptor address of the interrupt object to enable.

Returns:

0 is returned on success. Otherwise, -EINVAL is returned if a low-level error occurred while enabling the interrupt.

Environments:

This service can be called from:

• Kernel module initialization/cleanup code
• Kernel-based task
• User-space task

Rescheduling: never.

int xnintr_init	(	xnintr_t *	intr,
		const char *	name,
		unsigned	irq,
		xnisr_t	isr,
		xniack_t	iack,
		xnflags_t	flags
	)

Initialize an interrupt object.

Associates an interrupt object with an IRQ line.

When an interrupt occurs on the given irq line, the ISR is fired in order to deal with the hardware event. The interrupt service code may call any non-suspensive service from the nucleus.

Upon receipt of an IRQ, the ISR is immediately called on behalf of the interrupted stack context, the rescheduling procedure is locked, and the interrupt source is masked at hardware level. The status value returned by the ISR is then checked for the following values:

• XN_ISR_HANDLED indicates that the interrupt request has been fulfilled by the ISR.

• XN_ISR_NONE indicates the opposite to XN_ISR_HANDLED. The ISR must always return this value when it determines that the interrupt request has not been issued by the dedicated hardware device.

In addition, one of the following bits may be set by the ISR :

NOTE: use these bits with care and only when you do understand their effect on the system. The ISR is not encouraged to use these bits in case it shares the IRQ line with other ISRs in the real-time domain.

• XN_ISR_PROPAGATE tells the nucleus to require the real-time control layer to forward the IRQ. For instance, this would cause the Adeos control layer to propagate the interrupt down the interrupt pipeline to other Adeos domains, such as Linux. This is the regular way to share interrupts between the nucleus and the host system.

• XN_ISR_NOENABLE causes the nucleus to ask the real-time control layer _not_ to re-enable the IRQ line (read the following section). xnarch_end_irq() must be called to re-enable the IRQ line later.

The nucleus re-enables the IRQ line by default. Over some real-time control layers which mask and acknowledge IRQs, this operation is necessary to revalidate the interrupt channel so that more interrupts can be notified.

A count of interrupt receipts is tracked into the interrupt descriptor, and reset to zero each time the interrupt object is attached. Since this count could wrap around, it should be used as an indication of interrupt activity only.

Parameters:

	intr	The address of a interrupt object descriptor the nucleus will use to store the object-specific data. This descriptor must always be valid while the object is active therefore it must be allocated in permanent memory.
	name	An ASCII string standing for the symbolic name of the interrupt object or NULL ("<unknown>" will be applied then).
	irq	The hardware interrupt channel associated with the interrupt object. This value is architecture-dependent. An interrupt object must then be attached to the hardware interrupt vector using the xnintr_attach() service for the associated IRQs to be directed to this object.
	isr	The address of a valid low-level interrupt service routine if this parameter is non-zero. This handler will be called each time the corresponding IRQ is delivered on behalf of an interrupt context. When called, the ISR is passed the descriptor address of the interrupt object.
	iack	The address of an optional interrupt acknowledge routine, aimed at replacing the default one. Only very specific situations actually require to override the default setting for this parameter, like having to acknowledge non-standard PIC hardware. iack should return a non-zero value to indicate that the interrupt has been properly acknowledged. If iack is NULL, the default routine will be used instead.
	flags	A set of creation flags affecting the operation. The valid flags are:

• XN_ISR_SHARED enables IRQ-sharing with other interrupt objects.

• XN_ISR_EDGE is an additional flag need to be set together with XN_ISR_SHARED to enable IRQ-sharing of edge-triggered interrupts.

Returns:

No error condition being defined, 0 is always returned.

Environments:

This service can be called from:

• Kernel module initialization/cleanup code
• Kernel-based task
• User-space task

Rescheduling: never.

---