Module: xenomai-forge
Branch: next
Commit: 5964444b828d4f0a225064558d785ac66e8dcdd3

Author: Philippe Gerum <>
Date:   Tue Dec 31 16:49:00 2013 +0100

doc: add preliminary 2.x -> 3.x migration info


 doc/asciidoc/MIGRATION.adoc           |  471 +++++++++++++++++++++++++++++++++
 doc/asciidoc/              |    6 +-
 doc/asciidoc/              |    6 +-
 doc/asciidoc/README.APPLICATIONS.adoc |    4 +-
 doc/asciidoc/README.INSTALL.adoc      |    6 +-
 5 files changed, 482 insertions(+), 11 deletions(-)

diff --git a/doc/asciidoc/MIGRATION.adoc b/doc/asciidoc/MIGRATION.adoc
new file mode 100644
index 0000000..00c0d90
--- /dev/null
+++ b/doc/asciidoc/MIGRATION.adoc
@@ -0,0 +1,471 @@
+Migrating from Xenomai 2.x to {xenover}
+The latest version of this document is available at
+For questions, corrections and improvements, write to[the mailing list].
+File system updates
+- TBD.
+Real-time suitable STDIO support
+The former +include/rtdk.h+ header is gone in Xenomai
+3.x. Applications should include +include/stdio.h+ instead.
+Similarly, the real-time suitable STDIO routines are now part of
+Getting the system state
+Querying the state of the real-time system should be done via the new
+Xenomai registery interface available with Xenomai 3.x, which is
+turned on when +--enable-registry+ is passed to the configuration
+script for building the Xenomai libraries and programs.
+The new registry support is common to the Cobalt and Mercury cores,
+with only marginal differences due to the presence (or lack of) co-
+kernel in the system.
+/proc/xenomai interface changes
+The legacy /proc/xenomai interface is still available when running
+over the Cobalt core. The following changes compared to Xenomai 2.x
+took place though:
+- Thread status
+All pseudo-files reporting the various thread states moved under the
+new +sched/+ hierarchy, i.e.
++{sched, stat, acct}+ -> +sched/{threads, stat, acct}+
+- Clocks
+With the introduction of dynamic clock registration in the Cobalt
+core, the +clock/+ hierarchy was added, to reflect the current state
+of all timers from the registered Xenomai clocks.
+There is no kernel-based time base management anymore with Xenomai
+{xenover}. Functionally speaking, only the former _master_ time base
+remains, periodic timing is now controlled locally from the Xenomai
+libraries in user-space.
+Xenomai {xenover} defines a built-in clock named _coreclk_, which has
+the same properties than the former _master_ time base available with
+Xenomai 2.x (i.e. tickless with nanosecond resolution).
+As a consequence of these changes, The information once available from
++timerstat/master+ are now obtained by reading +clock/coreclk+, and
+the +timebases+ file was removed.
+- Core clock gravity
+The gravity value for a Xenomai clock gives the amount of time
+expressed in clock ticks, by which the next shot should be
+anticipated. This is a static adjustment value, to take into account
+the basic latency of the system for responding to an external event
+(hardware-wise, and software-wise). This value is commonly assessed by
+measuring the typical latency of an idle system.
+The +latency+ pseudo-file holds this value expressed as a count of
++latency+ now represents the sum of the scheduling *and* hardware
+timer reprogramming latencies of the core clock. This departs from
+Xenomai 2.x for which only the former was accounted for in the clock
+gravity value.
+- +interfaces+ was removed
+Only the POSIX and RTDM APIs remain implemented directly in kernel
+space. All other APIs are implemented in user-space over the
+Copperplate layer. This makes the former +interfaces+ contents
+basically useless, since the corresponding information for the
+POSIX/RTDM interfaces can be obtained via +sched/threads+.
+- +registry/usage+ changed format
+The new print out is %<used slot count>/%<total slot count>.
+Binary object features
+Loading Xenomai libraries dynamically
+The new +--enable-dlopen-libs+ configuration switch must be turned on
+to allow Xenomai libaries to be dynamically loaded via dlopen(3).
+This replaces the former +--enable-dlopen-skins+ switch. Unlike the
+latter, +--enable-dlopen-libs+ does not implicitly disable support for
+thread local storage, but rather selects a suitable TLS model
+(i.e. _global-dynamic_).
+Thread local storage
+The former +--with-__thread+ configuration switch was renamed
+As mentioned earlier, TLS is now available to dynamically loaded
+Xenomai libraries, e.g. +--enable-tls --enable-dlopen-libs+ on a
+configuration line is valid. This would select the _global-dynamic_
+TLS model instead of _initial-exec_, to make sure all thread-local
+variables may be accessed from any code module.
+Process-level management
+Main thread shadowing
+By default, any application linking against +libcobalt+ has its main
+thread attached to the real-time system automatically, this process is
+called _auto-shadowing_.
+This behavior may be disabled at runtime, by setting the XENO_NOSHADOW
+variable in the application process environment, before the
++libcobalt+ library constructors are executed.
+This replaces the former static mechanism available with Xenomai 2.x,
+based on turning on +--enable-dlopen-skins+ when configuring. Starting
+with Xenomai 3.x, applications should set the XENO_NOSHADOW variable
+using putenv(3), before loading +libcolbalt+ using dlopen(3).
+When auto-shadowing is enabled, global memory locking is also
+performed, and remains in effect afterwards
+(i.e. mlockall(MCL_CURRENT|MCL_FUTURE)).
+Shadow signal handler
+Xenomai's +libcobalt+ installs a handler for the SIGWINCH (aka
+_SIGSHADOW_) signal. This signal may be sent by the Cobalt core to any
+real-time application, for handling internal duties.
+Applications are allowed to interpose on the SIGSHADOW handler,
+provided they first forward all signal notifications to this routine,
+then eventually handle all events the Xenomai handler won't process.
+This handler was renamed from `xeno_sigwinch_handler()` (Xenomai 2.x)
+to `cobalt_sigshadow_handler()` in Xenomai 3.x. The function prototype
+did not change though, i.e.:
+int cobalt_sigshadow_handler(int sig, siginfo_t *si, void *ctxt)
+A non-zero value is returned whenever the event was handled internally
+by the Xenomai system.
+Debug signal handler
+Xenomai's +libcobalt+ installs a handler for the SIGXCPU (aka
+_SIGDEBUG_) signal. This signal may be sent by the Cobalt core to any
+real-time application, for notifying various debug events.
+Applications are allowed to interpose on the SIGDEBUG handler,
+provided they eventually forward all signal notifications they won't
+process to the Xenomai handler.
+This handler was renamed from `xeno_handle_mlock_alert()` (Xenomai
+2.x) to `cobalt_sigdebug_handler()` in Xenomai 3.x. The function
+prototype did not change though, i.e.:
++void cobalt_sigdebug_handler(int sig, siginfo_t *si, void *ctxt)+
+Copperplate auto-initialization
+Copperplate is a library layer which mediates between the real-time
+core services available on the platform, and the API exposed to the
+application. It provides typical programming abstractions for
+emulating real-time APIs. All non-POSIX APIs are based on Copperplate
+services (e.g. _alchemy_, _psos_, _vxworks_).
+When Copperplate is built for running over the Cobalt core, it sits on
+top of the +libcobalt+ library. Conversely, it is directly stacked on
+top of the *glibc* when built for running over the Mercury core.
+Normally, Copperplate should initialize from a call issued by the
++main()+ application routine. To make this process transparent for the
+user, the +xeno-config+ script emits link flags which temporarily
+overrides the +main()+ routine with a Copperplate-based replacement,
+running the proper initialization code as required, before branching
+back to the user-defined application entry point.
+This behavior may be disabled by passing the +--no-auto-init+ option
+(see the next section).
+Compilation helper script
+As with Xenomai 2.x, +xeno-config+ is available for retrieving the
+compilation and link flags for building Xenomai 3.x applications. This
+script will work for both the Cobalt and Mercury environments
+- The +--skin=+ option specifier has become optional. For instance,
+  mentioning +--skin=psos+ or +--psos+ on the command line is strictly
+  equivalent.
+- Specifying +--[skin=]cobalt+ or +--[skin=]posix+ on the command line
+  is strictly equivalent. However, this does not make sense with
+  _Mercury_ which does not define these switches.
+- +--[skin=]alchemy+ replaces the former +--skin=native+ switch.
+- +--core+ can be used to retrieve the name of the Xenomai core system
+  for which +xeno-config+ was generated. Possible output values are
+  +cobalt+ and +mercury+.
+- +--no-auto-init+ can be passed to disable automatic initialization
+  of the Copperplate library when the application process enters the
+  +main()+ routine. In such a case, the application code using any API
+  based on the Copperplate layer, shall call the +copperplate_init()+
+  routine manually, as part of its initialization process, _before_
+  any real-time service is invoked.
+POSIX interface changes
+As mentioned earlier, the former *POSIX skin* is known as the *Cobalt
+API* in Xenomai 3.x, available as +libcobalt.{so,a}+. The Cobalt API
+also includes the code of the former +libxenomai+, which is no more a
+standalone library.
++libcobalt+ exposes the set of POSIX and ISO/C standard features
+specifically implemented by Xenomai to honor real-time requirements
+using the Cobalt core.
+- The former +pthread_intr+ API once provided by Xenomai 2.x is gone.
+  Rationale: handling real-time interrupt events from user-space can
+  be done safely only if some bottom-half code exists for
+  acknowledging the issuing device request from kernel space. This
+  should be done via a RTDM driver, exposing a read(2) or ioctl(2)
+  interface, for waiting for interrupt events from applications
+  running in user-space.
+  Failing this, the low-level interrupt service code in user-space
+  would be sensitive to external thread management actions, such as
+  being stopped because of GDB/ptrace(2) interaction. Unfortunately,
+  preventing the device acknowledge code from running upon interrupt
+  request may cause unfixable breakage to happen (e.g. IRQ storm
+  typically).
+  Since the application should provide proper bottom-half code in a
+  dedicated RTDM driver for synchronizing on IRQ receipt, the RTDM API
+  available in user-space is sufficient.
+  Removing the +pthread_intr+ API should be considered as a
+  strong hint for keeping the bottom-half interrupt handling code in
+  kernel space.
+- Calling +pthread_setschedparam()+ may cause a secondary mode switch
+  for the caller, but does not cause any mode switch for the target
+  thread unlike with Xenomai 2.x.
+  This is a requirement for maintaining both the *glibc* and the
+  Xenomai scheduler in sync, with respect to thread priorities, since
+  the former maintains a process-local priority cache for the threads
+  it knows about. Therefore, an explicit call to the the regular
+  +pthread_setschedparam()+ shall be issued upon each priority change
+  Xenomai-wise, for maintaining consistency.
+  In the Xenomai 2.x implementation, the thread being set a new
+  priority would receive a SIGSHADOW signal, eventually handled as a
+  request to call *glibc*'s +pthread_setschedparam()+ immediately.
+  Rationale: the target Xenomai thread may hold a mutex or any
+  resource which may only be held in primary mode, in which case
+  switching to secondary mode for applying the priority change at
+  any random location over a signal handler may create a pathological
+  issue. In addition, *glibc*'s +pthread_setschedparam()+ is not
+  async-safe, which makes the former method fragile.
+  Conversely, a thread which calls +pthread_setschedparam()+ does know
+  unambiguously whether the current calling context is safe for such
+  request.
+- A new SCHED_WEAK class is available to POSIX threads, which may be
+  optionally turned on using the +CONFIG_XENO_OPT_SCHED_WEAK+ kernel
+  configuration switch.
+  By this feature, Xenomai now accepts Linux real-time scheduling
+  policies (SCHED_FIFO, SCHED_RR) to be weakly scheduled by the Cobalt
+  core, within a low priority scheduling class (i.e. below the Xenomai
+  real-time classes, but still above the idle class).
+  Xenomai 2.x already had a limited form of such policy, based on
+  scheduling SCHED_OTHER threads at the special SCHED_FIFO,0 priority
+  level in the Xenomai core. SCHED_WEAK is a generalization of such
+  policy, which provides for 99 priority levels, to cope with the full
+  extent of the regular Linux SCHED_FIFO/RR priority range.
+  For instance, a (non real-time) Xenomai thread within the SCHED_WEAK
+  class at priority level 20 in the Cobalt core, may be scheduled with
+  policy SCHED_FIFO/RR at priority 20, by the Linux kernel. The code
+  fragment below would set the scheduling parameters accordingly,
+  assuming the Cobalt version of +pthread_setschedparam()+ is invoked:
+       struct sched_param param = {
+              .sched_priority = -20,
+       };
+       pthread_setschedparam(tid, SCHED_FIFO, &param);
+  Switching a thread to the SCHED_WEAK class can be done by negating
+  the priority level in the scheduling parameters sent to the Cobalt
+  core. For instance, SCHED_FIFO, prio=-7 would be scheduled as
+  SCHED_WEAK, prio=7 by the Cobalt core.
+  SCHED_OTHER for a Xenomai-enabled thread is scheduled as
+  SCHED_WEAK,0 by the Cobalt core. When the SCHED_WEAK support is
+  disabled in the kernel configuration, only SCHED_OTHER is available
+  for weak scheduling of threads by the Cobalt core.
+- A new SCHED_QUOTA class is available to POSIX threads, which may be
+  optionally turned on using the +CONFIG_XENO_OPT_SCHED_QUOTA+ kernel
+  configuration switch.
+  This policy enforces a limitation on the CPU consumption of
+  threads over a globally defined period, known as the quota
+  interval. This is done by pooling threads with common requirements
+  in groups, and giving each group a share of the global period (see
+  When threads have entirely consumed the quota allotted to the group
+  they belong to, the latter is suspended as a whole, until the next
+  quota interval starts. At this point, a new runtime budget is given
+  to each group, in accordance with its share.
+- When called from primary mode, sched_yield() now relinquishes the
+  CPU in case no context switch happened as a result of the manual
+  round-robin.
+  Typically, a Xenomai thread undergoing the SCHED_FIFO or SCHED_RR
+  policy with no contender at the same priority level would still be
+  delayed for a while. This delay ends next time the regular Linux
+  kernel switches tasks, or a kernel (virtual) tick has elapsed
+  (TICK_NSEC), whichever comes first.
+  Rationale: it is most probably unwanted that sched_yield() does not
+  cause any context switch, since this service is commonly used for
+  implementing a poor man's cooperative scheduling. A typical use case
+  involves a Xenomai thread running in primary mode which needs to
+  yield the CPU to another thread running in secondary mode. By
+  waiting for a context switch to happen in the regular kernel, we
+  guarantee that the CPU has been relinquished for a while. By
+  limiting this delay, we prevent a regular high priority SCHED_FIFO
+  thread stuck in a tight loop, from locking out the delayed Xenomai
+  thread indefinitely.
+- The default POSIX thread stack size was raised to `PTHREAD_STACK_MIN
+  * 4`. The minimum stack size enforced by the +libcobalt+ library is
+  `PTHREAD_STACK_MIN + getpagesize()`.
+- Support for Xenomai real-time signals is available.
+Cobalt replacements for +sigwait()+, +sigwaitinfo()+, +sigtimedwait()+
+and +kill()+ are available. +pthread_kill()+ was changed to send
+thread-directed Xenomai signals (instead of regular Linux signals).
+Cobalt-based signals are stricly real-time. Both the sender and
+receiver sides work exclusively from the primary domain. However, only
+synchronous handling is available, with a thread waiting explicitly
+for a set of signals, using one of the +sigwait+ calls. There is no
+support for asynchronous delivery of signals to handlers.
+Signals from SIGRTMIN..SIGRTMAX are queued.
+COBALT_DELAYMAX is defined as the maximum number of overruns which can
+be reported by the Cobalt core in the siginfo.si_overrun field, for
+any signal.
+- +kill()+ supports group signaling.
+Cobalt's implementation of kill() behaves identically to the regular
+system call for non thread-directed signals (i.e. pid <= 0). In this
+case, the caller switches to secondary mode.
+Otherwise, Cobalt first attempts to deliver a thread-directed signal
+to the thread whose kernel TID matches the given process id. If this
+thread is not waiting for signals at the time of the call, kill() then
+attempts to deliver the signal to a thread from the same process,
+which currently waits for a signal.
+- +pthread_kill()+ is a conforming call.
+When Cobalt's replacement for +pthread_kill()+ is invoked, a
+Xenomai-enabled caller is automatically switched to primary mode on
+its way to sending the signal, under the control of the real-time
+co-kernel. Otherwise, the caller keeps running under the control of
+the regular Linux kernel.
+This behavior also applies to the new Cobalt-based replacement for the
++kill()+ system call.
+- POSIX timers are no more dropped when the creator thread
+  exits. However, they are dropped when the container process exits.
+- If the thread signaled by a POSIX timer exits, the timer is
+  automatically stopped at the first subsequent timeout which fails
+  sending the notification. The timer lingers until it is deleted or
+  when the process exits, whichever comes first.
+- timer_settime() may be called from a regular thread (i.e. which is
+  not Xenomai-enabled).
+- EPERM is not returned anymore by POSIX timer calls. EINVAL is
+  substituted in the corresponding situation.
+- The clock to be used for enabling periodic timing for a thread may
+  now be specified in the call to pthread_make_periodic_np():
+int pthread_make_periodic_np(pthread_t thread, clockid_t clk_id,
+    struct timespec *starttp, struct timespec *periodtp);
+- mq_open() default attributes align on the regular kernel values,
+  i.e. 10 msg x 8192 bytes (instead of 128 x 128).
+- mq_send() now enforces a maximum priority value for messages
+  (32768).
diff --git a/doc/asciidoc/ b/doc/asciidoc/
index c47f844..7ae9748 100644
--- a/doc/asciidoc/
+++ b/doc/asciidoc/
@@ -1,6 +1,6 @@
        asciidoc-icons asciidoc-icons/callouts asciidoc-css asciidoc-js
        plaintext.conf plaintext_postproc.awk plaintext.xsl
@@ -11,7 +11,7 @@ else
 ASCIIDOC_HTML_OPTS=-a icons -a iconsdir=../asciidoc-icons \
        -a linkcss -a stylesdir=../asciidoc-css -a scriptsdir=../asciidoc-js \
diff --git a/doc/asciidoc/ b/doc/asciidoc/
index 465f4fe..184b87e 100644
--- a/doc/asciidoc/
+++ b/doc/asciidoc/
@@ -296,10 +296,10 @@ target_vendor = @target_vendor@
 top_build_prefix = @top_build_prefix@
 top_builddir = @top_builddir@
 top_srcdir = @top_srcdir@
        asciidoc-icons asciidoc-icons/callouts asciidoc-css asciidoc-js
        plaintext.conf plaintext_postproc.awk plaintext.xsl
 @CONFIG_XENO_ASCIIDOC_FALSE@PDF_DOCSDIR = $(srcdir)/../generated/pdf/
iconsdir=../asciidoc-icons \
 @CONFIG_XENO_ASCIIDOC_TRUE@    -a linkcss -a stylesdir=../asciidoc-css -a 
scriptsdir=../asciidoc-js \
 @CONFIG_XENO_ASCIIDOC_TRUE@    -a toc -a toclevels=3 -a max-width=55em -a 
diff --git a/doc/asciidoc/README.APPLICATIONS.adoc 
index 0fe2832..a3a2deb 100644
--- a/doc/asciidoc/README.APPLICATIONS.adoc
+++ b/doc/asciidoc/README.APPLICATIONS.adoc
@@ -15,8 +15,8 @@ Compiling a Xenomai application
 You should use the +xeno-config+ script to get the proper compilation
-and linker flags related to Xenomai, for building your application,
-for whichever _Cobalt_ or _Mercury_ core.
+and linker flags related to Xenomai, in order to build your
+application for whichever _Cobalt_ or _Mercury_ core.
 Here is a trivial Makefile fragment retrieving the compiler and flags
 for building the single-file application +vxapp.c+, over the VxWorks
diff --git a/doc/asciidoc/README.INSTALL.adoc b/doc/asciidoc/README.INSTALL.adoc
index 10a68ff..4b79f4f 100644
--- a/doc/asciidoc/README.INSTALL.adoc
+++ b/doc/asciidoc/README.INSTALL.adoc
@@ -44,9 +44,9 @@ The +kernel/+ sub-tree which implements the in-kernel support 
code is
 seen as a built-in extension of the Linux kernel.  Therefore, the
 standard Linux kernel configuration process should be used to define
 the various settings for the Xenomai kernel components. All of the
-kernel code Xenomai currently introduces is for supporting the
-_Cobalt_ core (i.e. dual kernel configuration). As of today, the
-_Mercury_ core needs no Xenomai-specific code in kernel space.
+kernel code Xenomai currently introduces implements the _Cobalt_ core
+(i.e. dual kernel configuration). As of today, the _Mercury_ core
+needs no Xenomai-specific code in kernel space.
 The +lib/+ sub-tree contains the various user-space libraries exported
 by the Xenomai framework to the applications. This tree is built

Xenomai-git mailing list

Reply via email to