Interrupt management.
[Xenomai scheduler.]


Detailed Description

Interrupt management.


Files

file  intr.c
 Interrupt management.


Functions

int xnintr_init (xnintr_t *intr, unsigned irq, int priority, xnisr_t isr, xnist_t ist, 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.


Function Documentation

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/IST handlers.

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:
XN_OK is returned on success. Otherwise, XNERR_NOSYS is returned if a low-level error occurred while attaching the interrupt. XNERR_BUSY is specifically returned if the interrupt object was already attached.
Side-effect: This routine does not call the rescheduling procedure.

Context: This routine must be called on behalf of a thread or IST context.

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:
XN_OK is returned on success. Otherwise, XNERR_BUSY is returned if an error occurred while detaching the interrupt (see xnintr_detach()).
Side-effect: This routine calls the rescheduling procedure as a result of an interrupt service thread deleting its own interrupt object (this should rarely happen though).

Context: This routine must be called on behalf of a thread or IST context.

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/IST handlers, 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:
XN_OK is returned on success. Otherwise, XNERR_BUSY 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 XN_OK.
Side-effect: This routine does not call the rescheduling procedure.

Context: This routine must be called on behalf of a thread or IST context.

int xnintr_init xnintr_t *  intr,
unsigned  irq,
int  priority,
xnisr_t  isr,
xnist_t  ist,
xnflags_t  flags
 

Initialize an interrupt object.

The nanokernel defines a threaded interrupt model in order to:

  • provide a mean for prioritizing interrupt handling by software.

  • allow the interrupt code to synchronize with other system code using mutexes, therefore reducing the need for hard interrupt masking in critical sections.

Xenomai's nanokernel exhibits a split interrupt handling scheme separated into two parts. The first part is known as the Interrupt Service Routine (ISR), the second is the Interrupt Service Tasklet (IST).

When an interrupt occurs, the ISR is fired in order to deal with the hardware event as fast as possible, without any interaction with the nanokernel. If the interrupt service code needs to reenter the nanokernel, the ISR may require an associated interrupt service tasklet to be scheduled immediately upon return. The IST has a lightweight thread context that allows it to invoke all nanokernel services safely. A Xenomai interrupt object may be associated with an ISR and/or an IST to process each IRQ event.

[WARNING] Interrupt service threads/tasklets are deprecated in newer versions of the Xenomai nucleus, basically due to design and performance issues. Do not use the IST facility if you plan to port to RTAI/fusion.

Upon receipt of an IRQ, the ISR/IST invocation policy is as follows:

  • if an ISR has been defined, it is immediately called on behalf of the interrupt stack context.

  • if an IST has been defined, then its is scheduled upon return of the ISR if the XN_ISR_SCHED_T bit set in its return code or if no ISR has been defined for this interrupt object. The tasklet will run after all ISRs have completed and all more prioritary IST have returned. In any cases, the IST will run before any regular real-time threads (i.e. all but interrupt service threads).

If an ISR has been defined, the following bits are checked from its return value:

  • XN_ISR_ENABLE asks the nanokernel to re-enable the IRQ line. 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. The presence of such bit in the ISR's return code causes Xenomai to ask the real-time control layer to re-enable the interrupt.

  • XN_ISR_CHAINED tells the nanokernel 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 host system.

  • XN_ISR_SCHED_T tells the nanokernel to schedule the interrupt service tasklet (IST) which will be in charge of completing the interrupt processing on behalf of a lightweight thread context.

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.
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.
priority The priority level of the interrupt. If a valid interrupt service thread is passed in ist, this value will be used to compute the base priority of the service thread. This value must range from [0 .. XNINTR_MAX_PRIORITY] (inclusive). The higher the value, the higher the priority, whatever the current pod priority scheme is.
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.
ist If non-zero, this parameter should contain the address of a valid hi-level interrupt service tasklet. The tasklet will be called on behalf of an interrupt service thread each time the associated ISR sets the XN_ISR_SCHED_T bit in its return code. The underlying lightweight thread is immediately started with a stack of XNARCH_THREAD_STACKSZ bytes.
flags A set of creation flags affecting the operation. Since no flags are currently defined, zero should be passed for this parameter.
Returns:
XN_OK is returned upon success. Otherwise XNERR_PARAM is returned if the interrupt priority level is out of range.
Side-effect: This routine calls the rescheduling procedure as a result of starting the interrupt service thread (if any).

Context: This routine must be called on behalf of a thread context.


Generated on Sat Jul 24 19:36:22 2004 for RTAI API by doxygen 1.3.4