Interrupt management services.
[Native Xenomai API.]

Collaboration diagram for Interrupt management services.:

Files
file	intr.c
	This file is part of the Xenomai project.
Functions
int	rt_intr_create (RT_INTR *intr, const char *name, unsigned irq, rt_isr_t isr, rt_iack_t iack, int mode)
	Create an interrupt object from kernel space.
int	rt_intr_delete (RT_INTR *intr)
int	rt_intr_enable (RT_INTR *intr)
	Enable an interrupt object.
int	rt_intr_disable (RT_INTR *intr)
	Disable an interrupt object.
int	rt_intr_inquire (RT_INTR *intr, RT_INTR_INFO *info)
int	rt_intr_create (RT_INTR *intr, const char *name, unsigned irq, int mode)
	Create an interrupt object from user-space.
int	rt_intr_wait (RT_INTR *intr, RTIME timeout)
int	rt_intr_bind (RT_INTR *intr, const char *name, RTIME timeout)
static int	rt_intr_unbind (RT_INTR *intr)

---

Function Documentation

int rt_intr_bind	(	RT_INTR *	intr,
		const char *	name,
		RTIME	timeout
	)

Bind to an interrupt object.

This user-space only service retrieves the uniform descriptor of a given Xenomai interrupt object identified by its IRQ number. If the object does not exist on entry, this service blocks the caller until an interrupt object of the given number is created. An interrupt is registered whenever a kernel-space task invokes the rt_intr_create() service successfully for the given IRQ line.

Parameters:

	intr	The address of an interrupt object descriptor retrieved by the operation. Contents of this memory is undefined upon failure.
	name	An ASCII string standing for the symbolic name of the interrupt object to search for.
	timeout	The number of clock ticks to wait for the registration to occur (see note). Passing TM_INFINITE causes the caller to block indefinitely until the object is registered. Passing TM_NONBLOCK causes the service to return immediately without waiting if the object is not registered on entry.

Returns:

0 is returned upon success. Otherwise:

• -EFAULT is returned if intr is referencing invalid memory.

• -EINVAL is returned if irq is invalid.

• -EINTR is returned if rt_task_unblock() has been called for the waiting task before the retrieval has completed.

• -EWOULDBLOCK is returned if timeout is equal to TM_NONBLOCK and the searched object is not registered on entry.

• -ETIMEDOUT is returned if the object cannot be retrieved within the specified amount of time.

• -EPERM is returned if this service should block, but was called from a context which cannot sleep (e.g. interrupt, non-realtime or scheduler locked).

Environments:

This service can be called from:

• User-space task (switches to primary mode)

Rescheduling: always unless the request is immediately satisfied or timeout specifies a non-blocking operation.

Note:

The timeout value will be interpreted as jiffies if the native skin is bound to a periodic time base (see CONFIG_XENO_OPT_NATIVE_PERIOD), or nanoseconds otherwise.

int rt_intr_create	(	RT_INTR *	intr,
		const char *	name,
		unsigned	irq,
		int	mode
	)

Create an interrupt object from user-space.

Initializes and associates an interrupt object with an IRQ line from a user-space application. In this mode, the basic principle is to define some interrupt server task which routinely waits for the next incoming IRQ event through the rt_intr_wait() syscall.

When an interrupt occurs on the given irq line, any task pending on the interrupt object through rt_intr_wait() is imediately awaken in order to deal with the hardware event. The interrupt service code may then call any Xenomai service available from user-space.

Parameters:

	intr	The address of a interrupt object descriptor Xenomai 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. When non-NULL and non-empty, this string is copied to a safe place into the descriptor, and passed to the registry package if enabled for indexing the created interrupt objects.
	irq	The hardware interrupt channel associated with the interrupt object. This value is architecture-dependent.
	mode	The interrupt object creation mode. The following flags can be OR'ed into this bitmask:

• I_NOAUTOENA asks Xenomai not to re-enable the IRQ line before awakening the interrupt server task. This flag is functionally equivalent as always returning RT_INTR_NOENABLE from a kernel space interrupt handler.

• I_PROPAGATE asks Xenomai to propagate the IRQ down the pipeline; in other words, the interrupt occurrence is chained to Linux after it has been processed by the Xenomai task. This flag is functionally equivalent as always returning RT_INTR_PROPAGATE from a kernel space interrupt handler.

Returns:

0 is returned upon success. Otherwise:

• -ENOMEM is returned if the system fails to get enough dynamic memory from the global real-time heap in order to register the interrupt object.

• -EBUSY is returned if the interrupt line is already in use by another interrupt object. Only a single interrupt object can be associated to any given interrupt line using rt_intr_create() at any time, regardless of the caller's execution space (kernel or user).

Environments:

This service can be called from:

• User-space task

Rescheduling: possible.

Note:

The interrupt source associated to the interrupt descriptor remains masked upon creation. rt_intr_enable() should be called for the new interrupt object to unmask it.

Examples:

user_irq.c.

int rt_intr_create	(	RT_INTR *	intr,
		const char *	name,
		unsigned	irq,
		rt_isr_t	isr,
		rt_iack_t	iack,
		int	mode
	)

Create an interrupt object from kernel space.

Initializes and associates an interrupt object with an IRQ line. In kernel space, interrupts are immediately notified to a user-defined handler or ISR (interrupt service routine).

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 Xenomai service.

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:

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

• RT_INTR_NONE indicates the opposite to RT_INTR_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.

• RT_INTR_PROPAGATE tells Xenomai 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 Xenomai and the Linux kernel.

• RT_INTR_NOENABLE asks Xenomai not to re-enable the IRQ line upon return of the interrupt service routine.

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 Xenomai 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. When non-NULL and non-empty, this string is copied to a safe place into the descriptor, and passed to the registry package if enabled for indexing the created interrupt objects.
	irq	The hardware interrupt channel associated with the interrupt object. This value is architecture-dependent.
	isr	The address of a valid interrupt service routine in kernel space. This handler will be called each time the corresponding IRQ is delivered on behalf of an interrupt context. A pointer to an internal information is passed to the routine which can use it to retrieve the descriptor address of the associated interrupt object through the I_DESC() macro.
	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.
	mode	The interrupt object creation mode. The following flags can be OR'ed into this bitmask, each of them affecting the new interrupt object:

• I_SHARED enables IRQ-sharing with other interrupt objects.

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

Returns:

0 is returned upon success. Otherwise:

• -ENOMEM is returned if the system fails to get enough dynamic memory from the global real-time heap in order to register the interrupt object.

• -EBUSY is returned if the interrupt line is already in use by another interrupt object. Only a single interrupt object can be associated to any given interrupt line using rt_intr_create() at any time.

• -EEXIST is returned if irq is already associated to an existing interrupt object.

• -EPERM is returned if this service was called from an asynchronous context.

Environments:

This service can be called from:

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

Rescheduling: possible.

Note:

The interrupt source associated to the interrupt descriptor remains masked upon creation. rt_intr_enable() should be called for the new interrupt object to unmask it.

int rt_intr_delete

(

RT_INTR *

intr

)

Delete an interrupt object.

Destroys an interrupt object. An interrupt exists in the system since rt_intr_create() has been called to create it, so this service must be called in order to destroy it afterwards.

Any user-space task which might be currently pending on the interrupt object through the rt_intr_wait() service will be awaken as a result of the deletion, and return with the -EIDRM status.

Parameters:

intr

The descriptor address of the affected interrupt object.

Returns:

0 is returned upon success. Otherwise:

• -EINVAL is returned if intr is not a interrupt object descriptor.

• -EIDRM is returned if intr is a deleted interrupt object descriptor.

• -EPERM is returned if this service was called from an asynchronous context.

Environments:

This service can be called from:

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

Rescheduling: possible.

int rt_intr_disable

(

RT_INTR *

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 through rt_intr_enable().

Parameters:

intr

The descriptor address of the interrupt object to enable.

Returns:

0 is returned upon success. Otherwise:

• -EINVAL is returned if intr is not a interrupt object descriptor.

• -EIDRM is returned if intr is a deleted interrupt object descriptor.

Environments:

This service can be called from:

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

Rescheduling: never.

int rt_intr_enable

(

RT_INTR *

intr

)

Enable an interrupt object.

Enables the hardware interrupt line associated with an interrupt object. Over Adeos-based systems which mask and acknowledge IRQs upon receipt, this operation is necessary to revalidate the interrupt channel so that more interrupts from the same source can be notified.

Parameters:

intr

The descriptor address of the interrupt object to enable.

Returns:

0 is returned upon success. Otherwise:

• -EINVAL is returned if intr is not a interrupt object descriptor.

• -EIDRM is returned if intr is a deleted interrupt object descriptor.

Environments:

This service can be called from:

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

Rescheduling: never.

int rt_intr_inquire	(	RT_INTR *	intr,
		RT_INTR_INFO *	info
	)

Inquire about an interrupt object.

Return various information about the status of a given interrupt object.

Parameters:

	intr	The descriptor address of the inquired interrupt object.
	info	The address of a structure the interrupt object information will be written to.

Returns:

0 is returned and status information is written to the structure pointed at by info upon success. Otherwise:

• -EINVAL is returned if intr is not a interrupt object descriptor.

• -EIDRM is returned if intr is a deleted interrupt object descriptor.

Environments:

This service can be called from:

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

Rescheduling: never.

int rt_intr_unbind

(

RT_INTR *

intr

)

[inline, static]

Unbind from an interrupt object.

This user-space only service unbinds the calling task from the interrupt object previously retrieved by a call to rt_intr_bind().

Parameters:

intr

The address of a interrupt object descriptor to unbind from.

Returns:

0 is always returned.

This service can be called from:

• User-space task.

Rescheduling: never.

int rt_intr_wait	(	RT_INTR *	intr,
		RTIME	timeout
	)

Wait for the next interrupt.

This user-space only call allows the current task to suspend execution until the associated interrupt event triggers. The priority of the current task is raised above all other Xenomai tasks - except those also undergoing an interrupt or alarm wait (see rt_alarm_wait()) - so that it would preempt any of them under normal circumstances (i.e. no scheduler lock).

Interrupt receipts are logged if they cannot be delivered immediately to some interrupt server task, so that a call to rt_intr_wait() might return immediately if an IRQ is already pending on entry of the service.

Parameters:

	intr	The descriptor address of the awaited interrupt.
	timeout	The number of clock ticks to wait for an interrupt to occur (see note). Passing TM_INFINITE causes the caller to block indefinitely until an interrupt triggers. Passing TM_NONBLOCK is invalid.

Returns:

A positive value is returned upon success, representing the number of pending interrupts to process. Otherwise:

• -ETIMEDOUT is returned if no interrupt occurred within the specified amount of time.

• -EINVAL is returned if intr is not an interrupt object descriptor, or timeout is equal to TM_NONBLOCK.

• -EIDRM is returned if intr is a deleted interrupt object descriptor, including if the deletion occurred while the caller was waiting for its next interrupt.

• -EINTR is returned if rt_task_unblock() has been called for the current task before the next interrupt occurrence.

Environments:

This service can be called from:

• User-space task

Rescheduling: always, unless an interrupt is already pending on entry.

Note:

The timeout value will be interpreted as jiffies if the native skin is bound to a periodic time base (see CONFIG_XENO_OPT_NATIVE_PERIOD), or nanoseconds otherwise.

Examples:

user_irq.c.

---