Interruptions management services.
[POSIX skin.]

Collaboration diagram for Interruptions management services.:

---

Detailed Description

Interruptions management services.

The services described here allow applications written using the POSIX skin to handle interrupts, either in kernel-space or in user-space.

Note however, that it is recommended to use the standardized driver API of the RTDM skin (see Real-Time Driver Model).

Functions
int	pthread_intr_attach_np (pthread_intr_t *intrp, unsigned irq, int(*isr)(xnintr_t *), int(*iack)(unsigned irq))
	Create and attach an interrupt object.
int	pthread_intr_detach_np (pthread_intr_t intr)
	Destroy an interrupt object.
int	pthread_intr_control_np (pthread_intr_t intr, int cmd)
	Control the state of an interrupt channel.
int	pthread_intr_wait_np (pthread_intr_t intr, const struct timespec *to)
	Wait for the next interruption.

---

Function Documentation

int pthread_intr_attach_np	(	pthread_intr_t *	intrp,
		unsigned	irq,
		int(*)(xnintr_t *)	isr,
		int(*)(unsigned irq)	iack
	)

Create and attach an interrupt object.

This service creates and attaches an interrupt object.

In kernel-space:

This service installs isr as the handler for the interrupt irq. If iack is not null it is a custom interrupt acknowledge routine.

When called upon reception of an interrupt, the isr function is passed the address of an underlying xnintr_t object, and should use the macro PTHREAD_IDESC() to get the pthread_intr_t object. The meaning of the isr and iack function and what they should return is explained in xnintr_init() documentation.

This service is a non-portable extension of the POSIX interface.

Parameters:

	intrp	address where the created interrupt object identifier will be stored on success;
	irq	IRQ channel;
	isr	interrupt handling routine;
	iack	if not NULL, optional interrupt acknowledge routine.

In user-space:

The prototype of this service is :

int pthread_intr_attach_np (pthread_intr_t *intrp, unsigned irq, int mode);

This service causes the installation of a default interrupt handler which unblocks any Xenomai user-space interrupt server thread blocked in a call to pthread_intr_wait_np(), and returns a value depending on the mode parameter.

Parameters:

intrp and irq have the same meaning as in kernel-space; mode is a bitwise OR of the following values:

• PTHREAD_IPROPAGATE, meaning that the interrupt should be propagated to lower priority domains;
• PTHREAD_INOAUTOENA, meaning that the interrupt should not be automatically re-enabled.

This service is intended to be used in conjunction with the pthread_intr_wait_np() service.

The return values are identical in kernel-space and user-space.

Return values:

	0	on success;
	-1	with errno set if: ENOSYS, kernel-space Xenomai POSIX skin was built without support for interrupts, use RTDM or enable CONFIG_XENO_OPT_POSIX_INTR in kernel configuration; ENOMEM, insufficient memory exists in the system heap to create the interrupt object, increase CONFIG_XENO_OPT_SYS_HEAPSZ; EINVAL, a low-level error occured while attaching the interrupt; EBUSY, an interrupt handler was already registered for the irq line irq.

int pthread_intr_control_np	(	pthread_intr_t	intr,
		int	cmd
	)

Control the state of an interrupt channel.

This service allow to enable or disable an interrupt channel.

This service is a non-portable extension of the POSIX interface.

Parameters:

	intr	identifier of the interrupt to be enabled or disabled.
	cmd	one of PTHREAD_IENABLE or PTHREAD_IDISABLE.

Return values:

	0	on success;
	-1	with errno set if: ENOSYS, kernel-space Xenomai POSIX skin was built without support for interrupts, use RTDM or enable CONFIG_XENO_OPT_POSIX_INTR in kernel configuration; EINVAL, the identifier intr or cmd is invalid; EPERM, the interrupt intr does not belong to the current process.

int pthread_intr_detach_np

(

pthread_intr_t

intr

)

Destroy an interrupt object.

This service destroys the interrupt object intr. The memory allocated for this object is returned to the system heap, so further references using the same object identifier are not guaranteed to fail.

If a user-space interrupt server is blocked in a call to pthread_intr_wait_np(), it is unblocked and the blocking service returns with an error of EIDRM.

This service is a non-portable extension of the POSIX interface.

Parameters:

intr

identifier of the interrupt object to be destroyed.

Return values:

	0	on success;
	-1	with errno set if: ENOSYS, kernel-space Xenomai POSIX skin was built without support for interrupts, use RTDM or enable CONFIG_XENO_OPT_POSIX_INTR in kernel configuration; EINVAL, the interrupt object intr is invalid; EPERM, the interrupt intr does not belong to the current process.

int pthread_intr_wait_np	(	pthread_intr_t	intr,
		const struct timespec *	to
	)

Wait for the next interruption.

This service is used by user-space interrupt server threads, to wait, if no interrupt is pending, for the next interrupt.

This service is a cancelation point. If a thread is canceled while blocked in a call to this service, no interruption notification is lost.

This service is a non-portable extension of the POSIX interface.

Parameters:

	intr	interrupt object identifier;
	to	if not NULL, timeout, expressed as a time interval.

Returns:

the number of interrupt received on success;

-1 with errno set if:

• ENOSYS, kernel-space Xenomai POSIX skin was built without support for interrupts, use RTDM or enable CONFIG_XENO_OPT_POSIX_INTR in kernel configuration;
• EIDRM, the interrupt object was deleted;
• EPERM, the interrupt intr does not belong to the current process;
• ETIMEDOUT, the timeout specified by to expired;
• EINTR, pthread_intr_wait_np() was interrupted by a signal.

---