Life with Adeos

The fundamental Adeos structure one must keep in mind is the chain of client domains asking for event control. A domain is a kernel-based software component which can ask the Adeos layer to be notified of:

Adeos ensures that events are dispatched in an orderly manner to the various client domains according to their respective priority in the system, so it is possible to provide for timely and predictable delivery of such events. This is achieved by assigning each domain a static priority. This priority value strictly defines the delivery order of events to the domains. All active domains are queued according to their respective priority, forming the pipeline abstraction used by Adeos to make the events flow, from the highest to the lowest priority domain. Incoming events (including interrupts) are pushed to the head of the pipeline (i.e. to the highest priority domain) and progress down to its tail (i.e. to the lowest priority domain). The figure below gives a general view of some Adeos-based system, where multiple domains are sharing events through the pipeline abstraction:

Event pipeline representation

In the figure above, the position of the Linux kernel with respect to the pipelining order might be anywhere; this said, the Linux kernel still has a special role since it stands for the root domain, because all other domains need Linux to install them, usually by mean of loading the kernel modules which embody them.

In order to dispatch interrupts in an prioritized manner, while still allowing domains to create interrupt-free sections, Adeos implements the so-called Optimistic interrupt protection scheme as described by Stodolsky, Chen, and Bershad, in the following paper.

The stage of the pipeline occupied by any given domain can be stalled, which means that the next incoming interrupt will not be delivered to the domain's handler, and will be prevented from flowing down to the lowest priority domain(s) in the same move. While a stage is stalled, pending interrupts accumulate in the domain's interrupt log, and eventually get played when the stage is unstalled, by an internal operation called synchronization. Domains use this feature to protect their own critical sections from unwanted preemption by their own interrupt handlers. However, thanks to the virtualization of the interrupt control Adeos brings, a higher priority domain can still receive interrupts, and eventually preempt any lower priority domain. Practically, this means that, albeit an Adeos-enabled Linux kernel regularly stalls its own stage to perform critical operations, a real-time system running ahead of it in the pipeline would still be able to receive interrupts any time, with no incurred delay.

When a domain has finished processing all the pending interrupts it has received, it then calls a special Adeos service which yields the CPU to the next domain down the pipeline, so the latter can process in turn the pending events it has been notified of, and this cycle continues down to the lowest priority domain of the pipeline.

The figure below illustrates how several domains running on mutiple CPUs can share the incoming interrupts through the Adeos pipeline abstraction. Of course, a correct book-keeping of pending interrupts must be done while a stage is stalled: this is achieved by a per-domain, per-CPU interrupt log, as illustrated below:

The optimistic interrupt protection scheme

Interrupts are not the only kind of events which can flow through the pipeline abstraction; internal events triggered by the Linux kernel itself or its applications can generate what is called system events. Basically, system events are synchronous notifications of trap, exception, or some action performed by the Linux kernel, and which gets notified to any interested parties through the pipeline.

Since those events are synchronous by essence, there is no way to defer their notification through the stall operation, just because you cannot delay their handling. The rationale behind such design decision comes from the fact that a code triggering a system event might just not be able to continue without immediate intervention from the corresponding handler: e.g. the page fault handler must run immediately upon memory addressing exception, delaying it makes no sense. In other words, stall/unstall operations on any given domain only concern interrupts, either real or virtual.

Xenomai allows to run real-time threads either strictly in kernel space, or within the address space of a Linux process. In the rest of this article, we will refer to the latter as the Xenomai threads, not to be confused with regular Linux tasks (even when they belong to the SCHED_FIFO class). All threads managed by Xenomai are known from the real-time nucleus.

Support for real-time threads exclusively running in kernel space is a reminiscence of the mere co-kernel era, before the advent of true real-time support in user-space, when real-time applications would only run embodied into kernel modules; this feature has been kept in Xenomai mainly for the purpose of supporting legacy applications, and won't be discussed here.

What is more interesting is that Xenomai has a symbiotic approach with respect to Linux; this is, for instance, what makes it different from the RTAI/LXRT implementation. To this end, Xenomai threads are not only able to run over the context of the highest priority domain in the pipeline (i.e. the primary domain) like kernel-based Xenomai threads, but also in the regular Linux space (i.e. the secondary domain), while still being considered as real-time by Xenomai, albeit suffering higher scheduling latencies. In Xenomai's jargon, the former are said to run in primary execution mode, whilst the latter undergo the secondary execution mode.

In order to provide a complete real-time support to threads running in the secondary domain, Xenomai needs the following to be achieved:

As a consequence of the requirements above, when the Xenomai core is loaded, the underlying Adeos pipeline contains three stages, through which all interrupts are flowing, by order of priority:

The three stages of the Adeos pipeline

Since real-time APIs (i.e. skins) which are stackable over the Xenomai nucleus, can export their own set of services to Xenomai threads in user-space, there must be a way to properly dispatch the corresponding system calls, and the regular Linux kernel system calls altogether, to the proper handlers. To this end, Xenomai intercepts every system call trap/exception issued on behalf of any of the Xenomai or Linux domains by the Xenomai threads. This is made possible by subscribing an event handler using the proper Adeos service (for more on this, see the adeos_catch_event() service, when specifying the ADEOS_SYSCALL_PROLOGUE/IPIPE_EVENT_SYSCALL event). Xenomai uses this capability to:

The combination of both makes Xenomai threads particularly well integrated into the Linux realm. For instance, a common system call path for Xenomai and the regular Linux applications makes the former appear as a natural extension of the latter. As an illustration of this, Xenomai threads both support the full Linux signals semantics and ptracing feature, which in turn enables the GDB support natively for them.

Because it is ahead in the pipeline, the real-time nucleus which lives in the Xenomai domain is first notified of any incoming interrupt of interest, processes it, then marks such interrupt to be passed down the pipeline, eventually to the Linux kernel domain, if needed.

When notified from an incoming interrupt, the real-time nucleus reschedules after the outer interrupt handler has returned (in case interrupts are piling up), and switches in the highest priority runnable thread it controls.

The Xenomai domain yields the CPU to the interrupt shield domain when no real-time activity is pending, which in turn let them through whenever it is disengaged to the Linux kernel, or block them if engaged. Adeos has two basic propagation modes for interrupts through the pipeline:

This setting is defined on a per-domain, per-interrupt basis. Xenomai always uses the explicit mode for all interrupts it intercepts. This means that each handler must call the explicit propagation service to pass an incoming interrupt down the pipeline. When no handler is defined for a given interrupt by Xenomai, the interrupt is unconditionally propagated down to the Linux kernel: this keeps the system working when the real-time nucleus does not intercept such interrupt.

In addition to being able to stall a domain entirely so that no interrupt could flow through it anymore until it is explicitly unstalled, Adeos allows to selectively disable, and conversely re-enable, the actual source of interrupts, at hardware level.

After having taken over the box, Adeos handles the interrupt disabling requests for all domains, including for the Linux kernel and the real-time nucleus. This means disabling the interrupt source at the hardware PIC level, and locking out any interrupt delivery from this source to the current domain at the pipeline level. Conversely, enabling interrupts means reactivating the interrupt source at the PIC level, and allowing further delivery from this source to the current domain. Therefore, a domain enabling an interrupt source must be the same as the one which disabled it, because such operation is domain-dependent.

Practically, this means that, when used in pair, the rthal_irq_disable() and rthal_irq_enable() services which encapsulate the relevant Adeos calls inside the real-time HAL underlying Xenomai, must be issued from the same Adeos domain. For instance, if a real-time interrupt handler connected to some interrupt source using the rthal_irq_request() service, disables the source using rthal_irq_disable(), then such source will be blocked for the Xenomai domain until rthal_irq_enable() is called for the same interrupt, and from the same domain. Failing to deal with this requirement usually leads to the permanent loss of the affected interrupt channel.

A typical example of mis-using the Adeos pipeline when sharing hardware interrupts between domains is as follows:

void realtime_eth_handler (unsigned irq, void *cookie) 
{ 
    /* 
     * This interrupt handler has been installed using 
     * rthal_irq_request(), so it will always be invoked on behalf of 
     * the Xenomai (primary) domain. 
     */ 

    rthal_irq_disable(irq); 
    /* The Xenomai domain won't receive this irq anymore */
    
    rthal_irq_host_pend(irq); 
    /* This irq has been marked as pending for Linux */ 
}

void linux_eth_handler (int irq, void *dev_id, struct pt_regs *regs) 
{ 
    /* 
     * This interrupt handler has been installed using 
     * rthal_irq_host_request(), so it will always be invoked on 
     * behalf of the Linux (secondary) domain, as a shared interrupt 
     * handler (Linux-wise). 
     */ 
    rthal_irq_enable(irq); 
    
    /* 
     * BUG: This won't work as expected: we are only unlocking the 
     * interrupt source for the Linux domain which is current here, 
     * not for the Xenomai domain! 
     */ 
      

In the non-working example above, since Xenomai always uses the explicit propagation mode for all interrupts it intercepts, the next ethernet interrupt will be marked as pending in the Xenomai log only, waiting for the Xenomai handler to possibly propagate it manually down to Linux. But since the interrupt is still locked at pipeline level for Xenomai (remember that nobody actually issued the expected rthal_irq_enable() from the Xenomai domain, but only mistakenly from the Linux one), this won't happen, because the Xenomai handler won't run until the lock is removed. Therefore, well, chicken­and­egg problem: we are toast.

Fortunately, there is a solution for sharing interrupts properly, between domains which need to keep the interrupt source disabled until the final processing is done (e.g. dealing with level-triggered interrupts is one of those issues): actually, you don't need to do anything, because Adeos already masks any incoming interrupts at PIC level before feeding the pipeline with it. Therefore, you only need to process the interrupt as you see fit in the relevant domain handler, and make sure to re-enable the interrupt source from the last one using rthal_irq_enable(). Whenever the Linux kernel is one of those recipients, the regular kernel handler will do this re-enabling automatically, so basically, you just need to bother calling rthal_irq_enable() in handlers which don't propagate the incoming interrupts downstream to the Linux kernel.

Specifically on the x86 architecture, it happens that the timer interrupt is not being masked upon receipt by Adeos, for performances reasons. This said, the timer source is not one you may want to disable in any way, so this is a non­issue.

However, keeping an interrupt source masked while the propagation takes place through the entire pipeline may increase the latency.

Since Adeos guarantees that no stack overflow can occur due to interrupts piling up over any given domain, and because it also stalls the current stage before firing an interrupt handler, there is no need to disable the interrupt source in the Xenomai handler. Instead you may even want to re-enable it, so that further occurrences can be immediately logged, and will get played immediately after the current handler invocation returns.

So, the solution is to re-write the previous example this way, this time properly:

void realtime_eth_handler (unsigned irq, void *cookie) 
{ 
    rthal_irq_enable(irq); 
    rthal_irq_host_pend(irq); 
    /* This irq has been marked as pending for Linux */ 
}

void linux_eth_handler (int irq, void *dev_id, struct pt_regs *regs) 
{ 
    /* process the IRQ normally. */ 
}