Module: xenomai-forge
Branch: next
Commit: b8b861b28c727902b63a8ffe8e88ca634329a800
URL:    
http://git.xenomai.org/?p=xenomai-forge.git;a=commit;h=b8b861b28c727902b63a8ffe8e88ca634329a800

Author: Philippe Gerum <r...@xenomai.org>
Date:   Fri Sep 26 11:26:12 2014 +0200

doc: revamp top README

---

 README                   |   32 ++
 README.INSTALL           |  808 ----------------------------------------------
 TROUBLESHOOTING          |  622 -----------------------------------
 debian/rules             |    4 +-
 scripts/maint/resync-doc |    1 -
 5 files changed, 34 insertions(+), 1433 deletions(-)

diff --git a/README b/README
new file mode 100644
index 0000000..8f70ab5
--- /dev/null
+++ b/README
@@ -0,0 +1,32 @@
+
+Where to start from?
+====================
+
+http://xenomai.org/start-here/ is the best place to start learning
+about Xenomai 3.
+
+Built-in documentation
+======================
+
+The Xenomai 3.x documentation package for this release is directly
+available from the source tree, in HTML and PDF formats:
+
+doc/prebuilt/{html, pdf}/README.INSTALL
+doc/prebuilt/{html, pdf}/README.APPLICATIONS
+doc/prebuilt/{html, pdf}/MIGRATION
+doc/prebuilt/{html, pdf}/TROUBLESHOOTING.COBALT
+doc/prebuilt/{html, pdf}/TROUBLESHOOTING.MERCURY
+doc/prebuilt/{html, pdf}/xeno3prm
+
+Online documentation
+====================
+
+The online version of the documentation is available from our website
+for the current release:
+
+http://xenomai.org/installing-xenomai-3-x/
+http://xenomai.org/migrating-from-xenomai-2-x-to-3-x/
+http://xenomai.org/documentation/xenomai-3/html/xeno3prm/index.html
+http://xenomai.org/running-applications-with-xenomai-3-x/
+http://xenomai.org/troubleshooting-a-dual-kernel-configuration/
+http://xenomai.org/troubleshooting-a-single-kernel-configuration/
diff --git a/README.INSTALL b/README.INSTALL
deleted file mode 100644
index 504b691..0000000
--- a/README.INSTALL
+++ /dev/null
@@ -1,808 +0,0 @@
-Installing Xenomai 3.x
-
--------------------------------------------------------------------------------
-
-Table of Contents
-
-1. Introduction
-2. Installation steps
-3. Installing the Cobalt core
-
-    3.1. Preparing the Cobalt kernel
-    3.2. Configuring and compiling the Cobalt kernel
-    3.3. Examples of building the Cobalt kernel
-
-        Building a Cobalt/x86 kernel (32/64bit)
-        Building a Cobalt/powerpc kernel (32/64bit)
-        Building a Cobalt/blackfin kernel
-        Building Cobalt/arm kernel
-
-
-5. Installing the Xenomai libraries and tools
----------------------------------------------
-
-    5.1. Prerequisites
-
-        Generic requirements (both cores)
-        Cobalt-specific requirements
-        Mercury-specific requirement
-
-    5.2. Configuring
-
-        Generic configuration options (both cores)
-        Cobalt-specific configuration options
-
-    5.3. Cross-compilation
-
-
-6. Examples of building the Xenomai libraries and tools
--------------------------------------------------------
-
-    6.1. Building the x86 libraries (32/64bit)
-    6.2. Building the PPC32 libraries
-    6.3. Building the PPC64 libraries
-    6.4. Building the Blackfin libraries
-    6.5. Building the ARM libraries
-
-
-7. Testing the installation
----------------------------
-
-    7.1. Booting the Cobalt kernel
-    7.2. Testing the real-time system (both cores)
-
-
-9. Migrating applications to Xenomai 3
---------------------------------------
-
-
-1. Introduction
----------------
-
-Xenomai 3 is the new architecture of the Xenomai real-time framework, which can
-run seamlessly side-by-side Linux as a co-kernel system like Xenomai 2, or
-natively over mainline Linux kernels. In the latter case, the mainline kernel
-can be supplemented by the PREEMPT-RT patch: 
-"https://www.kernel.org/pub/linux/kernel/projects/rt/"; to meet stricter 
response time requirements than standard
-kernel preemption would bring.
-
-This new architecture therefore exhibits two real-time cores, selected at build
-time. The dual kernel core nicknamed Cobalt, is a significant rework of the
-Xenomai 2.x system. The native linux version, an enhanced implementation of the
-experimental Xenomai/SOLO: 
-"http://www.osadl.org/Migration-Portability.migration-portability.0.html"; 
work, is called Mercury.
-
-This magic works with the introduction of the Copperplate interface, which
-mediates between the real-time API/emulator your application uses, and the
-underlying real-time core. This way, applications are able to run in either
-environments without visible code change.
-
-
-2. Installation steps
----------------------
-
-Xenomai follows a split source model, decoupling the kernel space support from
-the user-space libraries.
-
-To this end, kernel and user-space Xenomai components are respectively
-available under the kernel/ and lib/ sub-trees. Other top-level directories,
-such as scripts/, testsuite/ and utils/, provide additional scripts and
-programs to be used on either the build host, or the runtime target.
-
-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
-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 separately from the
-kernel support. Libraries are built in order to support the selected core,
-either Cobalt or Mercury.
-
-
-3. Installing the Cobalt core
------------------------------
-
-
-3.1. Preparing the Cobalt kernel
---------------------------------
-
-Xenomai/cobalt provides a real-time extension kernel seamlessly integrated to
-Linux, therefore the first step is to build it as part of the target kernel. To
-this end, scripts/prepare-kernel.sh is a shell script which sets up the target
-kernel properly. The syntax is as follows:
-
-$ scripts/prepare-kernel.sh [--linux=<linux-srctree>]
-[--ipipe=<ipipe-patch>] [--arch=<target-arch>]
-
---linux
-    specifies the path of the target kernel source tree. Such kernel tree may
-    be already configured or not, indifferently. This path defaults to $PWD.
---ipipe
-    specifies the path of the interrupt pipeline (aka I-pipe) patch to apply
-    against the kernel tree. Suitable patches are available with Xenomai/cobalt
-    under kernel/cobalt/arch/<target-arch>/patches. This parameter can be
-    omitted if the I-pipe has already been patched in, or the script shall
-    suggest an appropriate one. The script will detect whether the interrupt
-    pipeline code is already present into the kernel tree, and skip this
-    operation if so.
---arch
-    tells the script about the target architecture. If unspecified, the build
-    host architecture suggested as a reasonable default.
-
-For instance, the following command would prepare the Linux tree located at /
-home/me/linux-3.10-ipipe in order to patch the Xenomai support in:
-
-$ cd xenomai-forge
-$ scripts/prepare-kernel.sh --linux=/home/me/linux-3.10
-
-Note: The script will infer the location of the Xenomai kernel code from its
-own location within the Xenomai source tree. For instance, if /home/me/
-xenomai-forge/scripts/prepare-kernel.sh is executing, then the Xenomai kernel
-code available from /home/me/xenomai-forge/kernel/cobalt will be patched in the
-target Linux kernel.
-
-
-3.2. Configuring and compiling the Cobalt kernel
-------------------------------------------------
-
-Once prepared, the target kernel can be configured as usual. All Xenomai
-configuration options are available from the "Xenomai" toplevel Kconfig menu.
-
-There are several important kernel configuration options, documented in the
-TROUBLESHOOTING guide.
-
-Once configured, the kernel can be compiled as usual.
-
-If you want several different configs/builds at hand, you may reuse the same
-source by adding O=../build-<target> to each make invocation.
-
-In order to cross-compile the Linux kernel, pass an ARCH and CROSS_COMPILE
-variable on make command line. See sections "Building a Cobalt/arm kernel",
-"Building a Cobalt/powerpc kernel", "Building a Cobalt/blackfin kernel",
-"Building a Cobalt/x86 kernel", for examples.
-
-
-3.3. Examples of building the Cobalt kernel
--------------------------------------------
-
-The examples in following sections use the following conventions:
-
-$linux_tree
-    path to the target kernel sources
-$xenomai_root
-    path to the Xenomai sources
-
-Building a Cobalt/x86 kernel (32/64bit)
-
-Building Xenomai/cobalt for x86 is almost the same for 32bit and 64bit
-platforms. You should note, however, that it is not possible to run Xenomai
-libraries compiled for x86_32 on a kernel compiled for x86_64, and conversely.
-
-Assuming that you want to build natively for a x86_64 system (x86_32
-cross-build options from x86_64 appear between brackets), you would typically
-run:
-
-$ cd $linux_tree
-$ $xenomai_root/scripts/prepare-kernel.sh --arch=x86 \
-  
--ipipe=$xenomai_root/kernel/cobalt/arch/x86/patches/ipipe-core-X.Y.Z-x86-NN.patch
-$ make [ARCH=i386] xconfig/gconfig/menuconfig
-
-?configure the kernel (see also the recommended settings here).
-
-Enable Xenomai options, then build with:
-
-$ make [ARCH=i386] bzImage modules
-
-Now, let?s say that you really want to build Xenomai for a Pentium-based x86
-32bit platform, using the native host toolchain; the typical steps would be as
-follows:
-
-$ cd $linux_tree
-$ $xenomai_root/scripts/prepare-kernel.sh --arch=i386 \
-  
--ipipe=$xenomai_root/kernel/cobalt/arch/x86/patches/ipipe-core-X.Y.Z-x86-NN.patch
-$ make xconfig/gconfig/menuconfig
-
-?configure the kernel (see also the recommended settings here).
-
-Enable Xenomai options, then build with:
-
-$ make bzImage modules
-
-Similarly, for a 64bit platform, you would use:
-
-$ cd $linux_tree
-$ $xenomai_root/scripts/prepare-kernel.sh --arch=x86_64 \
-  
--ipipe=$xenomai_root/kernel/cobalt/arch/x86/patches/ipipe-core-X.Y.Z-x86-NN.patch
-$ make xconfig/gconfig/menuconfig
-
-?configure the kernel (see also the recommended settings here).
-
-Enable Xenomai options, then build with:
-
-$ make bzImage modules
-
-The remaining examples illustrate how to cross-compile a Cobalt-enabled kernel
-for various architectures. Of course, you would have to install the proper
-cross-compilation toolchain for the target system first.
-
-Building a Cobalt/powerpc kernel (32/64bit)
-
-A typical cross-compilation setup, in order to build Xenomai for a ppc-6xx
-architecture running a 3.10.32 kernel. We use the DENX ELDK cross-compiler:
-
-$ cd $linux_tree
-$ $xenomai_root/scripts/prepare-kernel.sh --arch=powerpc \
-  
--ipipe=$xenomai_root/kernel/cobalt/arch/powerpc/patches/ipipe-core-3.10.32-powerpc-1.patch
-$ make ARCH=powerpc CROSS_COMPILE=ppc_6xx- xconfig/gconfig/menuconfig
-
-?select the kernel and Xenomai options, save the configuration
-
-$ make ARCH=powerpc CROSS_COMPILE=powerpc-linux- uImage modules
-
-?manually install the kernel image and modules to the proper location
-
-Building a Cobalt/blackfin kernel
-
-The Blackfin is a MMU-less, DSP-type architecture running uClinux.
-
-$ cd $linux_tree
-$ $xenomai_root/scripts/prepare-kernel.sh --arch=blackfin \
-  
--ipipe=$xenomai_root/kernel/cobalt/arch/blackfin/patches/ipipe-core-X.Y.Z-x86-NN.patch
-$ make ARCH=blackfin CROSS_COMPILE=bfin-uclinux- xconfig/gconfig/menuconfig
-
-?select the kernel and Xenomai options, then compile with:
-
-$ make linux image
-
-?then install as needed
-
-$ cp images/linux /tftpboot/...
-
-Building Cobalt/arm kernel
-
-Using codesourcery toolchain named arm-none-linux-gnueabi-gcc and compiling for
-a CSB637 board (AT91RM9200 based), a typical compilation will look like:
-
-$ cd $linux_tree
-$ $xenomai_root/scripts/prepare-kernel.sh --arch=arm \
-  
--ipipe=$xenomai_root/kernel/cobalt/arch/arm/patches/ipipe-core-X.Y.Z-x86-NN.patch
-$ mkdir -p $build_root/linux
-$ make ARCH=arm CROSS_COMPILE=arm-none-linux-gnueabi- O=$build_root/linux \
-  csb637_defconfig
-$ make ARCH=arm CROSS_COMPILE=arm-none-linux-gnueabi- O=$build_root/linux \
-  bzImage modules
-
-?manually install the kernel image, system map and modules to the proper
-location
-
-
-4. Installing the Mercury core
-------------------------------
-
-For Mercury, you need no Xenomai-specific kernel support so far, beyond what
-your host Linux kernel already provides. Your kernel should at least provide
-high resolution timer support (CONFIG_HIGH_RES_TIMERS), and likely complete
-preemption (PREEMPT_RT) if your application requires short and bounded
-latencies.
-
-Kernels with no real-time support can be used too, likely for basic debugging
-tasks, and/or running applications which do not have strict response time
-requirements.
-
-Therefore, unlike with Cobalt, there is no additional steps for preparing and/
-or configuring the kernel for Mercury.
-
-
-5. Installing the Xenomai libraries and tools
----------------------------------------------
-
-
-5.1. Prerequisites
-------------------
-
-Generic requirements (both cores)
-
-  * GCC must have support for legacy atomic builtins (__sync form).
-  * GCC should have a (sane/working) support for TLS preferably, although this
-    is not mandatory if building with --disable-tls.
-
-Cobalt-specific requirements
-
-  * The kernel version must be 3.10 or better.
-  * An interrupt pipeline (I-pipe) patch must be available for your target
-    kernel. You can find the official patches issued by the Xenomai project
-    there: "http://download.gna.org/adeos/patches/v3.x/";. Only patches from the
-    ipipe-core series are appropriate, legacy patches from the adeos-ipipe
-    series are not.
-  * A timestamp counter (TSC) is required from running on a x86_32 hardware.
-    Unlike with Xenomai 2.x, TSC-emulation using a PIT register is not
-    available.
-
-Mercury-specific requirement
-
-  * There is no particular requirement for Mercury setups, although using a
-    NPTL-based glibc or uClibc is recommended.
-
-
-5.2. Configuring
-----------------
-
-A common autoconf script prepares for building the libraries and programs, for
-both the Cobalt and Mercury cores. The core-specific code which may be needed
-internally is automatically and transparently selected at compilation-time by
-the build process.
-
-The options listed below can be passed to this script.
-
-Generic configuration options (both cores)
-
---with=core=       Indicates which real-time core you want to build the support
-<type>             libraries for, namely cobalt or mercury. This option
-                   defaults to cobalt.
-
---prefix=<dir>     Specifies the root installation path for libraries, include
-                   files, scripts and executables. Running $ make install
-                   installs these files to $DESTDIR/<dir>. This directory
-                   defaults to /usr/xenomai.
-
---enable-debug[=   This switch controls the debug level. Three levels are
-partial]           available, with varying overhead:
-
-                     * symbols enables debug symbols to be compiled in the
-                       libraries and executables, still turning on the
-                       optimizer (-O2). This option has no overhead, it is
-                       useful to get meaningful backtraces using gdb while
-                       running the application at nominal speed.
-                     * partial includes symbols, and also turns on internal
-                       consistency checks within the Xenomai code (mostly
-                       present in the Copperplate layer). The CONFIG_XENO_DEBUG
-                       macro is defined, for both the Xenomai libraries and the
-                       applications getting their C compilation flags from the
-                       xeno-config script (i.e. xeno-config --cflags). The
-                       partial debug mode implicitly turns on --enable-assert.
-                       A measurable overhead is introduced by this level. This
-                       is the default level when --enable-debug is mentioned
-                       with no level specification.
-                     * full includes partial settings, but the optimizer is
-                       disabled (-O0), and even more consistency checks may be
-                       performed. In addition to __XENO_DEBUG__, the macro
-                       CONFIG_XENO_DEBUG_FULL is defined. This level introduces
-                       the most overhead, which may triple the worst-case
-                       latency, or even more.
-
-                       Over the Mercury core, enabling partial or full debug
-                       modes also causes the standard malloc interface to be
-                       used internally instead of a fast real-time allocator
-                       (TLSF). This allows debugging memory-related issues with
-                       the help of Valgrind or other dynamic memory analysers.
-
---disable-debug    Fully turns off all consistency checks and assertions, turns
-                   on the optimizer and disables debug symbol generation.
-
---enable-assert    A number of debug assertion statements are present into the
-                   Xenomai libraries, checking the internal consistency of the
-                   runtime system dynamically (see man assert(3)). Passing
-                   --disable-assert to the configure script disables built-in
-                   assertions unconditionally. By default, assertions are
-                   enabled in partial or full debug modes, disabled otherwise.
-
---enable-pshared   Enable shared multi-processing. When enabled, this option
-                   allows multiple processes to share real-time objects (e.g.
-                   tasks, semaphores).
-
---enable-registry  Xenomai APIs can export their internal state through a
-                   pseudo-filesystem, which files may be read to obtain
-                   information about the existing real-time objects, such as
-                   tasks, semaphores, message queues and so on. This feature is
-                   supported by FUSE: "http://fuse.sourceforge.net/";, which
-                   must be available on the target system. Building the Xenomai
-                   libraries with the registry support requires the FUSE
-                   development libraries to be installed on the build system.
-
-                   When this option is enabled, the system creates a file
-                   hierachy under /mnt/xenomai/<session>.<pid> (by default),
-                   where you can access the internal state of the active
-                   real-time objects. The session label is obtained from the
-                   --session runtime switch. E.g. looking at the properties of
-                   a VxWorks task could be done as follows:
-
-                $ cat /mnt/xenomai/anon.12656/vxworks/tasks/windTask
-                name       = windTask
-                errno      = 0
-                status     = ready
-                priority   = 70
-                lock_depth = 0
-
-You may override the default root of the registry hierarchy by using the
---registry-root runtime option (see below).
-
-[Note] Note
-       When running over Xenomai/cobalt, the /proc/xenomai interface is also
-       available for inspecting the core system state.
-
---enable-lores-clock
-    Enables support for low resolution clocks. By default, libraries are built
-    with no support for tick-based timing. If you need such support (e.g. for
-    pSOS ? or VxWorks ? APIs), then you can turn it on using this option.
-
-[Note] Note
-       The POSIX API does not support tick-based timing. Alchemy may use it
-       optionally.
-
---enable-clock-monotonic-raw
-    The Xenomai libraries requires a monotonic clock to be available from the
-    underlying POSIX interface. When CLOCK_MONOTONIC_RAW is available on your
-    system, you may want to pass this switch, otherwise CLOCK_MONOTONIC will be
-    used by default.
-
-[Note] Note
-       The Cobalt core implements CLOCK_MONOTONIC_RAW, so this switch is turned
-       on by default when building with --with-core=cobalt. On the contrary,
-       this option is turned off by default when building for the Mercury core,
-       since we don?t know in advance whether this feature does exist on the
-       target kernel.
-
---enable-tls
-
-    Xenomai can use GCC?s thread local storage extension (TLS) to speed up the
-    retrieval of the per-thread information it uses internally. This switch
-    enables TLS, use the converse --disable-tls to prevent this.
-
-    Due to GCC bugs regarding this feature with some release,architecture
-    combinations, whether TLS is turned on by default is a per-architecture
-    decision. Currently, this feature is enabled for x86 and powerpc by
-    default, other architectures will require --enable-tls to be passed to the 
-    configure script explicitly.
-
-    Unless --enable-dlopen-libs is present, the initial-exec TLS model is
-    selected.
-
-    When TLS is disabled, POSIX?s thread-specific data management services are
-    used internally (i.e. pthread_set/getspecific()).
-
---enable-dlopen-libs
-
-    This switch allows programs to load Xenomai-based libraries dynamically,
-    using the dlopen(3) routine. Enabling dynamic loading introduces some
-    overhead in TLS accesses when enabled (see --enable-tls), which might be
-    noticeable depending on the architecture.
-
-    To support dynamic loading when --enable-tls is turned on, the 
-    global-dynamic TLS model is automatically selected.
-
-    Applications loading libcobalt.so dynamically may want to create the
-    XENO_NOSHADOW environment variable prior to calling dlopen(), to prevent
-    auto-shadowing of the calling context.
-
-    Dynamic loading of Xenomai-based libraries is disabled by default.
-
---enable-async-cancel
-
-    Enables fully asynchronous cancellation of Xenomai threads created by the
-    real-time APIs, making provision to protect the Xenomai implementation code
-    accordingly.
-
-    When disabled, Xenomai assumes that threads may exit due to cancellation
-    requests only when they reach cancellation points (like system calls).
-    Asynchronous cancellation is disabled by default.
-
-[Caution] Caution
-          Fully asynchronous cancellation can easily lead to resource leakage,
-          silent corruption, safety issues and all sorts of rampant bugs. The
-          only reason to turn this feature on would be aimed at cancelling
-          threads which run significantly long, syscall-less busy loops with no
-          explicit exit condition, which should probably be revisited anyway.
-
---enable-smp
-    Turns on SMP support for Xenomai libraries.
-
-[Caution] Caution
-          SMP support must be enabled in Xenomai libraries when the client
-          applications are running over a SMP-capable kernel.
-
---disable-sanity
-    Turns off the sanity checks performed at application startup by the Xenomai
-    libraries. This option sets a default, which can later be overriden using
-    the --[no-]sanity options passed to a Copperplate-based Xenomai
-    application. Sanity checks are enabled by default when configuring.
---enable-fortify
-    Enables support for applications compiled in _FORTIFY_SOURCE mode.
---disable-valgrind-client
-    Turns off the Valgrind client support, forcing CONFIG_XENO_VALGRIND_API off
-    in the Xenomai configuration header.
---enable-doc-build
-
-    Causes the inline Xenomai documentation based on the Doxygen markup
-    language: "http://doxygen.org"; to be produced as PDF and HTML documents.
-    Additional documentation like manpages based on the Asciidoc markup
-    language: "http://asciidoc.org/"; is produced too.
-
-    A pre-built copy of the documentation is present in the source tree, under
-    the doc/generated/ file hierarchy.
-
---disable-doc-install
-    Disables the copying of the pre-built documentation to the installation
-    directory.
-
-Cobalt-specific configuration options
-
-        NAME                            DESCRIPTION                    DEFAULT
-
---enable-x86-vsyscall  Use the x86/vsyscall interface for issuing      enabled
-                       syscalls. If disabled, the legacy 0x80 vector
-                       will be used. Turning on this option requires
-                       NPTL.
-
---enable-arm-tsc       Enable ARM TSC emulation. ^[a]                  kuser
-
---enable-arm-quirks    Enable quirks for specific ARM SOCs Currently   disabled
-                       sa1100 and xscale3 are supported.
-
-^[a] In the unusual situation where Xenomai does not support the kuser generic
-emulation for the target SOC, use this option to specify another tsc emulation
-method. See --help for a list of valid values.
-
-^[1]
-
-
-5.3. Cross-compilation
-----------------------
-
-In order to cross-compile the Xenomai libraries and programs, you will need to
-pass a --host and --build option to the configure script. The --host option
-allow to select the architecture for which the libraries and programs are
-built. The --build option allows to choose the architecture on which the
-compilation tools are run, i.e. the system running the configure script.
-
-Since cross-compiling requires specific tools, such tools are generally
-prefixed with the host architecture name; for example, a compiler for the
-PowerPC architecture may be named powerpc-linux-gcc.
-
-When passing --host=powerpc-linux to configure, it will automatically use
-powerpc-linux- as a prefix to all compilation tools names and infer the host
-architecture name from this prefix. If configure is unable to infer the
-architecture name from the cross-compilation tools prefix, you will have to
-manually pass the name of all compilation tools using at least the CC and LD,
-variables on configure command line.
-
-The easiest way to build a GNU cross-compiler might involve using crosstool-ng,
-available here: "http://crosstool-ng.org/";.
-
-If you want to avoid to build your own cross compiler, you might if find easier
-to use the ELDK. It includes the GNU cross development tools, such as the
-compilers, binutils, gdb, etc., and a number of pre-built target tools and
-libraries required on the target system. See here: 
-"http://www.denx.de/wiki/DULG/ELDK"; for further details.
-
-Some other pre-built toolchains:
-
-  * Mentor Sourcery CodeBench Lite Edition, available here: 
-"http://www.mentor.com/embedded-software/sourcery-tools/sourcery-codebench/editions/lite-edition/";;
-  * Linaro toolchain (for the ARM architecture), available here: 
-"https://launchpad.net/linaro-toolchain-binaries";.
-
-
-6. Examples of building the Xenomai libraries and tools
--------------------------------------------------------
-
-The examples in following sections use the following conventions:
-
-$xenomai_root
-    path to the Xenomai sources
-$build_root
-    path to a clean build directory
-$staging_dir
-    path to a directory that will hold the installed file temporarily before
-    they are moved to their final location; when used in a cross-compilation
-    setup, it is usually a NFS mount point from the target?s root directory to
-    the local build host, as a consequence of which running make{nbsp}DESTDIR=
-    $staging_dir{nbsp}install on the host immediately updates the target system
-    with the installed programs and libraries.
-
-[Caution] Caution
-          In the examples below, make sure to add --enable-smp to the configure
-          script options if building for a SMP-enabled kernel.
-
-
-6.1. Building the x86 libraries (32/64bit)
-------------------------------------------
-
-Assuming that you want to build the Mercury libraries natively for a x86_64/SMP
-system, enabling shared multi-processing support. You would typically run:
-
-$ mkdir $build_root && cd $build_root
-$ $xenomai_root/configure --with-core=mercury --enable-smp --enable-pshared
-$ make install
-
-Conversely, cross-building the Cobalt libraries from x86_64 with the same
-feature set, for running on x86_32 could be:
-
-$ mkdir $build_root && cd $build_root
-$ $xenomai_root/configure --with-core=cobalt --enable-smp --enable-pshared \
-  --host=i686-linux CFLAGS="-m32 -O2" LDFLAGS="-m32"
-$ make install
-
-After installing the build tree (i.e. using "make install"), the installation
-root should be populated with the librairies, programs and header files you can
-use to build Xenomai-based real-time applications. This directory path defaults
-to /usr/xenomai.
-
-The remaining examples illustrate how to cross-compile Xenomai for various
-architectures. Of course, you would have to install the proper
-cross-compilation toolchain for the target system first.
-
-
-6.2. Building the PPC32 libraries
----------------------------------
-
-A typical cross-compilation setup, in order to build the Cobalt libraries for a
-ppc-6xx architecture. In that example, we want the debug symbols to be
-generated for the executable, with no runtime overhead though. We use the DENX
-ELDK cross-compiler:
-
-$ cd $build_root
-$ $xenomai_root/configure --host=powerpc-linux --with-core=cobalt \
-  --enable-debug=symbols
-$ make DESTDIR=$staging_dir install
-
-
-6.3. Building the PPC64 libraries
----------------------------------
-
-Same process than for a 32bit PowerPC target, using a crosstool-built toolchain
-for ppc64/SMP.
-
-$ cd $build_root
-$ $xenomai_root/configure --host=powerpc64-unknown-linux-gnu \
-  --with-core=cobalt --enable-smp
-$ make DESTDIR=$staging_dir install
-
-
-6.4. Building the Blackfin libraries
-------------------------------------
-
-Another cross-compilation setup, in order to build the Cobalt libraries for the
-Blackfin architecture. We use ADI?s toolchain: 
-"http://blackfin.uclinux.org/doku.php?id=toolchain:installing"; for this 
purpose:
-
-$ mkdir $build_root && cd $build_root
-$ $xenomai_root/configure --host=bfin-linux-uclibc --with-core=cobalt
-$ make DESTDIR=$staging_dir install
-
-[Note] Note
-       Xenomai uses the FDPIC shared library format on this architecture. In
-       case of problem running the testsuite, try restarting the last two build
-       steps, passing the --disable-shared option to the "configure" script.
-
-
-6.5. Building the ARM libraries
--------------------------------
-
-Using codesourcery toolchain named arm-none-linux-gnueabi-gcc and compiling for
-a CSB637 board (AT91RM9200 based), a typical cross-compilation from a x86_32
-desktop would look like:
-
-$ mkdir $build_root/xenomai && cd $build_root/xenomai
-$ $xenomai_root/configure CFLAGS="-march=armv4t" LDFLAGS="-march=armv4t" \
-  --build=i686-pc-linux-gnu --host=arm-none-linux-gnueabi- --with-core=cobalt
-$ make DESTDIR=$staging_dir install
-
-[Important] Important
-            Unlike previous releases, Xenomai no longer passes any arm
-            architecture specific flags, or FPU flags to gcc, so, users are
-            expected to pass them using the CFLAGS and LDFLAGS variables as
-            demonstrated above, where the AT91RM9200 is based on the ARM920T
-            core, implementing the armv4 architecture. The following table
-            summarizes the CFLAGS and options which were automatically passed
-            in previous revisions and which now need to be explicitely passed
-            to configure, for the supported SOCs:
-
-Table 1. ARM configure options and compilation flags
-
-    SOC                    CFLAGS                      configure options
-
-at91rm9200    -march=armv4t -msoft-float
-
-at91sam9x     -march=armv5 -msoft-float
-
-imx1          -march=armv4t -msoft-float
-
-imx21         -march=armv5 -msoft-float
-
-imx31         -march=armv6 -mfpu=vfp
-
-imx51/imx53   -march=armv7-a -mfpu=vfp3 ^[a]
-
-imx6q         -march=armv7-a -mfpu=vfp3 ^[a]     --enable-smp
-
-ixp4xx        -march=armv5 -msoft-float          --enable-arm-tsc=ixp4xx
-
-omap3         -march=armv7-a -mfpu=vfp3 ^[a]
-
-omap4         -march=armv7-a -mfpu=vfp3 ^[a]     --enable-smp
-
-orion         -march=armv5 -mfpu=vfp
-
-pxa           -march=armv5 -msoft-float
-
-pxa3xx        -march=armv5 -msoft-float          --enable-arm-quirks=xscale3
-
-s3c24xx       -march=armv4t -msoft-float
-
-sa1100        -march=armv4t -msoft-float         --enable-arm-quirks=sa1100
-
-^[a] Depending on the gcc versions the flag for armv7 may be -march=armv7-a or
--march=armv7a
-
-
-It is possible to build for an older architecture version (v6 instead of v7, or
-v4 instead of v5), if your toolchain does not support the target architecture,
-the only restriction being that if SMP is enabled, the architecture should not
-be less than v6.
-
-
-7. Testing the installation
----------------------------
-
-
-7.1. Booting the Cobalt kernel
-------------------------------
-
-In order to test the Xenomai installation over Cobalt, you should first try to
-boot the patched kernel. Check the kernel boot log for messages like these:
-
-$ dmesg | grep -i xenomai
-I-pipe: head domain Xenomai registered.
-[Xenomai] Cobalt vX.Y.Z enabled
-
-If the kernel fails booting, or the log messages indicates an error status
-instead, see the TROUBLESHOOTING guide.
-
-
-7.2. Testing the real-time system (both cores)
-----------------------------------------------
-
-First, run the latency test:
-
-$ /usr/xenomai/bin/latency
-
-The latency test should display a message every second with minimum, maximum
-and average latency values. If this test displays an error message, hangs, or
-displays unexpected values, see the TROUBLESHOOTING guide.
-
-If the latency test succeeds, you should try next to run the xeno-test test in
-order to assess the worst-case latency of your system. Try:
-
-$ xeno-test --help
-
-
-8. Building and running Xenomai 3 applications
-----------------------------------------------
-
-Once the latency test behaves as expected on your target system, it is deemed
-ready to run real-time applications.
-
-You may want to have a look at this document for details about the application
-build process.
-
-In addition, you should refer to this document to learn about the builtin
-command line switches available with any Xenomai 3 application.
-
-
-9. Migrating applications to Xenomai 3
---------------------------------------
-
-If you plan to port an existing application based on Xenomai 2.x to Xenomai
-
-3.x, you should have a look at this migration guide.
-----------------------------------------------------
-
-
--------------------------------------------------------------------------------
-
-^[1] Each option enabled by default can be forcibly disabled by passing
---disable-<option> to the configure script
-
diff --git a/TROUBLESHOOTING b/TROUBLESHOOTING
deleted file mode 100644
index f75d9b7..0000000
--- a/TROUBLESHOOTING
+++ /dev/null
@@ -1,622 +0,0 @@
-Troubleshooting guide for Xenomai 3.x
-
--------------------------------------------------------------------------------
-
-Table of Contents
-
-1. Kernel configuration
-2. Xenomai or I-pipe error in the kernel log
-
-    2.1. The kernel stops after "Uncompressing Linux? done, booting the
-        kernel."
-    2.2. The kernel stops with an OOPS
-    2.3. The kernel boots but does not print any message
-    2.4. I-pipe: could not find timer for cpu #x
-    2.5. Xenomai: Local APIC absent or disabled!
-    2.6. Xenomai: SMI-enabled chipset found, but SMI workaround disabled
-    2.7. Xenomai: system init failed, code -19
-
-        On x86
-        On other supported platforms
-        On a new I-pipe port
-
-    2.8. Xenomai: system init failed, code -22
-
-
-3. Problems when running the latency test
------------------------------------------
-
-    3.1. Xenomai: --enable-x86-sep needs NPTL and Linux 2.6.x or higher
-    3.2. latency: failed to open benchmark device
-    3.3. Hardware tsc is not a fast wrapping one
-    3.4. Xenomai: incompatible ABI revision level
-    3.5. Xenomai: incompatible feature set
-
-        missing="kuser_tsc"
-        missing="sep"
-        missing="smp/nosmp"
-        missing="tsc"
-
-    3.6. Xenomai: kernel/user tsc emulation mismatch
-    3.7. Xenomai: native skin or CONFIG_XENO_OPT_PERVASIVE disabled
-    3.8. latency: not found
-    3.9. Xenomai: Your board/configuration does not allow tsc emulation
-    3.10. the latency test hangs
-    3.11. the latency test shows high latencies
-    3.12. ARM tsc emulation issues
-
-
-5. Problem with my code (not Xenomai code)
-------------------------------------------
-
-    5.1. "Warning: <service> is deprecated" while compiling kernel code
-    5.2. High latencies when transitioning from primary to secondary mode
-    5.3. Any Xenomai service fails with code -38 (ENOSYS)
-    5.4. My application reserves a lot of memory
-
-This file is a troubleshooting guide about various known issues regarding
-Xenomai 3.x.
-
-
-1. Kernel configuration
------------------------
-
-When configuring the Linux kernel, some options should be avoided.
-
-CONFIG_CPU_FREQ
-    This allows the CPU frequency to be modulated with workload, but many CPUs
-    change the TSC counting frequency also, which makes it useless for accurate
-    timing when the CPU clock can change. Also some CPUs can take several
-    milliseconds to ramp up to full speed.
-CONFIG_CPU_IDLE
-    Allows the CPU to enter deep sleep states, increasing the time it takes to
-    get out of these sleep states, hence the latency of an idle system. Also,
-    on some CPU, entering these deep sleep states causes the timers used by
-    Xenomai to stop functioning.
-CONFIG_KGDB
-    This option can not be enabled with current versions of the I-pipe patch.
-
-For x86 specific options see also this page: 
-"http://www.xenomai.org/index.php/Configuring_x86_kernels";.
-
-
-2. Xenomai or I-pipe error in the kernel log
---------------------------------------------
-
-If the Xenomai and I-pipe messages do not appear in the kernel log as:
-
-I-pipe: head domain Xenomai registered.
-Xenomai: hal/<arch> started.
-Xenomai: scheduling class idle registered.
-Xenomai: scheduling class rt registered.
-Xenomai: real-time nucleus v2.6.1 (Light Years Away) loaded.
-Xenomai: debug mode enabled.
-Xenomai: starting native API services.
-Xenomai: starting POSIX services.
-Xenomai: starting RTDM services.
-
-Where <arch> is the architecture you use, check the following sections, they
-describe the usual error messages you may encounter.
-
-
-2.1. The kernel stops after "Uncompressing Linux? done, booting the kernel."
-----------------------------------------------------------------------------
-
-This means that the kernel crashes before the console is enabled. You should
-enable the CONFIG_EARLY_PRINTK option. For some architectures (blackfin, x86,
-arm), enabling this option also requires passing the earlyprintk parameter on
-the kernel command line. See Documentation/kernel-parameters.txt for possible
-values.
-
-For the ARM architecture, you have to enable CONFIG_DEBUG_KERNEL and
-CONFIG_DEBUG_LL in order to be able to enable CONFIG_EARLY_PRINTK.
-
-
-2.2. The kernel stops with an OOPS
-----------------------------------
-
-Please make sure that you have followed the "Kernel configuration" section.
-Then, try capturing the oops text (using a serial console or netconsole) post
-the oops to the xenomai mailing list: "xeno...@xenomai.org", with the kernel
-configuration you used to compile the failing kernel.
-
-
-2.3. The kernel boots but does not print any message
-----------------------------------------------------
-
-Your distribution may be configured to pass the quiet option on the kernel
-command line. In this case, the kernel does not print all the log messages,
-however, they are still available using the dmesg command.
-
-
-2.4. I-pipe: could not find timer for cpu #x
---------------------------------------------
-
-See code -19.
-
-
-2.5. Xenomai: Local APIC absent or disabled!
---------------------------------------------
-
-See code -19.
-
-
-2.6. Xenomai: SMI-enabled chipset found, but SMI workaround disabled
---------------------------------------------------------------------
-
-First you should run the latency test under some load and see if you experience
-any pathological latency ("pathological" meaning more than, say, 100
-micro-seconds). If you do not observe any such latency, then this warning is
-harmless, and if you find it annoying, you may disable "SMI detection" in
-Xenomai?s configuration menu. You can skip the rest of this section.
-
-If you observe any high latency then you have a problem with SMI, and this
-warning was intended for you. But the Xenomai configuration menu allow you to
-enable two workarounds which may help you. These workarounds may be found in
-the Machine/SMI workaround sub-menu of Xenomai configuration menu.
-
-The first workaround which you should try is to disable all SMI sources. In
-order to do this, in the Xenomai configuration menu, select the options "Enable
-SMI workaround" and "Globally disable SMI". This option is the safest
-workaround, because when enabled, no SMI can interfere with hardware interrupt
-management behind your back and cause high latencies. Once this workaround
-enabled, you should run the latency test again, verify that your high latency
-disappeared but most importantly, verify that every peripheral you intend to
-use with Xenomai is working properly. If everything is working properly, then
-you are done with SMI.
-
-If some peripheral is not working properly, then it probably needs SMI, in
-which case you can not simply disable SMI globally, you will need to disable
-all SMI sources on your system except the SMI needed by your peripheral. This
-is a much less safe choice, since Xenomai has to know all SMI sources to
-disable them, one by one. In order to choose this second workaround, unselect
-the option "Globally disable SMI", and select the option corresponding to your
-peripheral. For example, if you need legacy USB emulation to get your USB mouse
-working, select the option "Enable legacy USB emulation". You should then run
-the latency test again and verify that you do not observe any high latency and
-that all your peripherals are functioning correctly. If you can not find your
-peripheral in the list proposed in the Xenomai configuration menu, drop a mail
-to the Xenomai mailing list: "xeno...@xenomai.org", we will try and possibly
-add the proper option if needed. If when running the latency test again, your
-peripheral is working properly and you still observe high latencies, then you
-are out of luck, the peripheral you want is likely to be the cause of such
-latencies.
-
-[Important] Important
-            On some systems, SMI may be involved in thermal throttling of the
-            CPU. Thus, switching it off can cause hardware damage in overheat
-            situations. Do not disable SMIs if you are in this case.
-
-
-2.7. Xenomai: system init failed, code -19
-------------------------------------------
-
-The most probable reason is that Xenomai could not find a timer.
-
-Check that you have not enabled one of the options in the "Kernel
-configuration" section.
-
-On x86
-
-You will most likely also see the following message:
-
-Xenomai: Local APIC absent or disabled!
-Disable APIC support or pass "lapic" as bootparam.
-
-Xenomai sends this message if the kernel configuration Xenomai was compiled
-against enables the local APIC support (CONFIG_X86_LOCAL_APIC), but the
-processor status gathered at boot time by the kernel says that no local APIC
-support is available. There are two options for fixing this issue:
-
-  * either your CPU really has no local APIC hw, then you need to rebuild a
-    kernel with LAPIC support disabled, before rebuilding Xenomai against the
-    latter;
-  * or it does have a local APIC but the kernel boot parameters did not specify
-    to activate it using the "lapic" option. The latter is required since
-    2.6.9-rc4 for boxen which APIC hardware is disabled by default by the BIOS.
-    You may want to look at the file Documentation/kernel-parameters.txt from
-    the Linux source tree, for more information about this parameter.
-
-On other supported platforms
-
-As on x86, on other platforms where Xenomai shares the timer with Linux, the
-timer is only used if it was not shut down by Linux. So you should check the
-log for messages about disabled timers. You can also check /proc/timer_list to
-see which timers are enabled. For instance, Xenomai on SMP systems requires
-per-cpu local timers, so the local timers should be enabled. In case of doubt,
-post a message to the xenomai mailing list: "xeno...@xenomai.org", sending:
-
-  * your kernel configuration
-  * the contents of /proc/timer_list run on the exact kernel which has the
-    issue
-  * the complete kernel boot log.
-
-On a new I-pipe port
-
-You will most likely also see the following message:
-
-I-pipe: could not find timer for cpu #x
-
-Starting with the I-pipe patch for Linux 3.2, the timers provided by the I-pipe
-patch to Xenomai are registered at run-time. So, you may lack a struct
-ipipe_timer definition, and its registration with ipipe_timer_register() or
-with the ipipe_timer member of the struct clock_event_device structure.
-
-For an example on the ARM platform see this page: 
-"http://www.xenomai.org/index.php/I-pipe-core:ArmPorting#The_general_case";.
-
-
-2.8. Xenomai: system init failed, code -22
-------------------------------------------
-
-On the ppc64 platform, check whether CONFIG_PPC_64K_PAGES is defined in your
-kernel configuration. If so, then you likely need to raise all Xenomai
-parameters defining the size of internal heaps, such as
-CONFIG_XENO_OPT_SYS_HEAPSZ, CONFIG_XENO_OPT_GLOBAL_SEM_HEAPSZ and
-CONFIG_XENO_OPT_SEM_HEAPSZ, so that (size / 64k) > 2. The default values for
-these parameters are currently based on the assumption that PAGE_SIZE = 4k.
-
-
-3. Problems when running the latency test
------------------------------------------
-
-The first test to run to see if Xenomai is running correctly on your platform
-is the latency test. The following sections describe the usual reasons for this
-test not to run correctly.
-
-
-3.1. Xenomai: --enable-x86-sep needs NPTL and Linux 2.6.x or higher
--------------------------------------------------------------------
-
-On the x86 architecture, the configure script option --enable-x86-sep allows
-Xenomai to use the SYSENTER/SYSEXIT mechanism for issuing system calls.
-
-However, this mechanism requires support from the libc. Currently, we know the
-glibc with NPTL has this support, other libraries will cause Xenomai
-applications to fail with this error message.
-
-
-3.2. latency: failed to open benchmark device
----------------------------------------------
-
-You have launched latency -t 1 or latency -t 2 which both require the kernel to
-have been configured with the CONFIG_XENO_DRIVERS_TIMERBENCH option.
-
-
-3.3. Hardware tsc is not a fast wrapping one
---------------------------------------------
-
-See the "ARM tsc emulation issues" section.
-
-
-3.4. Xenomai: incompatible ABI revision level
----------------------------------------------
-
-Each Xenomai branch (2.1, 2.2, 2.3, 2.4, 2.5, 2.6,?) defines a kernel/user ABI,
-so that it is possible to mix kernels and user-space supports of different
-versions in the same branch. So, for instance, after having build a system with
-a kernel and user-space support using Xenomai 2.6.0, it is possible to update
-the user-space support to Xenomai 2.6.1 without changing the kernel.
-
-However, it is not possible to mix kernel and user-space supports of different
-branches.
-
-A common reason for this error is when you run a kernel compiled with Xenomai
-2.6.1 support on a system where you have a user-space installed by your Debian
-based Linux distribution (notably Ubuntu) from the 2.5 branch, this can not
-work, the two branches use different ABIs. See README.INSTALL for details on
-how to compile a user-space support, or to build a new xenomai-runtime Debian
-package.
-
-If you compiled and installed the correct Xenomai user-space support, there are
-probably files on your system remaining from a previous installation.
-
-
-3.5. Xenomai: incompatible feature set
---------------------------------------
-
-Since kernel-space support and user-space support are compiled separately, each
-Xenomai application checks, at startup, whether the kernel and user-space
-supports have been configured with compatible options. If you see this message,
-it means they have not. See README.INSTALL for further details. The following
-sections detail the most frequent reasons for this message.
-
-missing="kuser_tsc"
-
-See the "ARM tsc emulation issues" section.
-
-missing="sep"
-
-On the x86 architecture, the configure script option --enable-x86-sep allows
-Xenomai to use the SYSENTER/SYSEXIT mechanism for issuing system calls.
-
-However, this mechanism requires a recent kernel (2.6 or higher).
-
-missing="smp/nosmp"
-
-For kernel-space and user-space supports to be compatible, both should be
-compiled with the same setting for SMP.
-
-SMP support in kernel-space is enabled with the CONFIG_SMP option.
-
-SMP support in user-space is enabled by passing --enable-smp to the configure
-script, and disabled by passing --disable-smp (SMP is enabled by default on
-some platforms).
-
-missing="tsc"
-
-This error is specific to the x86 architecture. You enabled tsc in user-space
-by passing the --enable-x86-tsc option, but you selected a processor when
-configuring the kernel which has no tsc.
-
-So, if your processor has a tsc (all Intel processors starting with some
-Pentium and Pentium Pro have a tsc), you probably mis-configured your kernel
-and should select the exact processor you are using in the kernel configuration
-and recompile it.
-
-If your processor does not have a tsc, you should not pass the --enable-x86-tsc
-option to the configure script.
-
-
-3.6. Xenomai: kernel/user tsc emulation mismatch
-------------------------------------------------
-
-See the "ARM tsc emulation issues" section.
-
-
-3.7. Xenomai: native skin or CONFIG_XENO_OPT_PERVASIVE disabled
----------------------------------------------------------------
-
-Possible reasons for this error are:
-
-  * you booted a kernel without Xenomai or I-pipe support, a kernel with I-pipe
-    and Xenomai support should have a /proc/ipipe/version and /proc/xenomai/
-    version files;
-  * the kernel you booted does not have the CONFIG_XENO_SKIN_NATIVE and
-    CONFIG_XENO_OPT_PERVASIVE options enabled;
-  * Xenomai failed to start, check the "Xenomai or I-pipe error in the kernel
-    log" section;
-  * you are trying to run Xenomai user-space support compiled for x86_32 on an
-    x86_64 kernel.
-
-
-3.8. latency: not found
------------------------
-
-On the ARM platform this message happens when there is a mismatch between
-kernel and user for the EABI setting: for instance you compiled the user-space
-support with a toolchain generating OABI code, and are trying to run the result
-on a kernel with CONFIG_AEABI but without CONFIG_OABI_COMPAT. Or vice versa,
-when running user-space compiled with an EABI toolchain on a kernel without
-CONFIG_AEABI.
-
-
-3.9. Xenomai: Your board/configuration does not allow tsc emulation
--------------------------------------------------------------------
-
-See the "ARM tsc emulation issues" section.
-
-
-3.10. the latency test hangs
-----------------------------
-
-The most common reason for this issues is a too short period passed with the -p
-option, try increasing the period.
-
-
-3.11. the latency test shows high latencies
--------------------------------------------
-
-The latency test runs, but you are seeing high latencies.
-
-  * make sure that you carefully followed the "Kernel configuration" section.
-  * make sure that you do not have an issue with SMIs, see the section about
-    SMIs. Note that if you have an Intel chipset and you do not see the
-    message:
-
-Xenomai: SMI-enabled chipset found, but SMI workaround disabled
-
-in the boot logs, it may mean that your chipset is not detected.
-
-  * if you have some legacy USB switch at BIOS configuration level, try
-    disabling it.
-  * if you do not have this option at BIOS configuration level, it does not
-    necessarily mean that there is no support for it, thus no potential for
-    high latencies; this support might just be forcibly enabled at boot time.
-    To solve this, in case your machine has some USB controller hardware, make
-    sure to enable the corresponding host controller driver support in your
-    kernel configuration. For instance, UHCI-compliant hardware needs
-    CONFIG_USB_UHCI_HCD. As part of its init chores, the driver should reset
-    the host controller properly, kicking out the BIOS off the concerned
-    hardware, and deactivate the USB legacy mode if set in the same move.
-  * if you observe high latencies while running X-window, try disabling
-    hardware acceleration in the X-window server file; in the Device section of
-    /etc/X11/XF86Config-4 add the following line:
-
-        Option "NoAccel"
-
-
-3.12. ARM tsc emulation issues
-------------------------------
-
-In order to allow applications to measure short durations with as little
-overhead as possible, Xenomai uses a 64 bits high resolution counter. On x86,
-the counter used for this purpose is the time-stamp counter, with its "rdtsc"
-instruction.
-
-ARM processors generally do not have a 64 bits high resolution counter
-available in user-space, so this counter is emulated by reading whatever high
-resolution counter is available on the processor, and used as clock source in
-kernel-space, and extend it to 64 bits by using data shared with the kernel. If
-Xenomai libraries are compiled without emulated tsc support, system calls are
-used, which have a much higher overhead than the emulated tsc code.
-
-In recent versions of the I-pipe patch, SOCs generally select the
-CONFIG_IPIPE_ARM_KUSER_TSC option, which means that the code for reading this
-counter is provided by the kernel at a predetermined address (in the vector
-page, a page which is mapped at the same address in every process) and is the
-code used if you do not pass the --enable-arm-tsc or --disable-arm-tsc option
-to configure, or pass --enable-arm-tsc=kuser.
-
-This default should be fine with recent patches and most ARM SOCs.
-
-However, if you see the following message:
-
-Xenomai: incompatible feature set
-(userland requires "kuser_tsc...", kernel provides..., missing="kuser_tsc")
-
-It means that you are either using an old patch, or that the SOC you are using
-does not select the CONFIG_IPIPE_ARM_KUSER_TSC option (to this date the only
-in-tree SOC family not using this option is ixp4xx).
-
-So you should resort to what Xenomai did before branch 2.6: select the tsc
-emulation code when compiling Xenomai user-space support by using the
---enable-arm-tsc option. The parameter passed to this option is the name of the
-SOC or SOC family for which you are compiling Xenomai. Typing:
-
-/patch/to/xenomai/configure --help
-
-will return the list of valid values for this option.
-
-If after having enabled this option and recompiled, you see the following
-message when starting the latency test:
-
-Xenomai: kernel/user tsc emulation mismatch
-
-or
-
-Hardware tsc is not a fast wrapping one
-
-It means that you selected the wrong SOC or SOC family, reconfigure Xenomai
-user-space support by passing the right parameter to --enable-arm-tsc and
-recompile.
-
-The following message:
-
-Xenomai: Your board/configuration does not allow tsc emulation
-
-means that the kernel-space support for the SOC you are using does not provide
-support for tsc emulation in user-space. In that case, you should recompile
-Xenomai user-space support passing the --disable-arm-tsc option.
-
-
-4. switchtest fails with "pthread_create: Resource temporarily unavailable"
----------------------------------------------------------------------------
-
-The switchtest test creates many kernel threads, this means that the option
-CONFIG_XENO_OPT_SYS_HEAPSZ should be set to large enough values. Try increasing
-it and recompiling.
-
-
-5. Problem with my code (not Xenomai code)
-------------------------------------------
-
-
-5.1. "Warning: <service> is deprecated" while compiling kernel code
--------------------------------------------------------------------
-
-Where <service> is a thread creation service, one of:
-
-  * cre_tsk
-  * pthread_create
-  * rt_task_create
-  * sc_tecreate or sc_tcreate
-  * taskSpawn or taskInit
-  * t_create
-
-Starting with Xenomai 3, the skins will not export their interface to kernel
-modules anymore, at the notable exception of the RTDM device driver API, which
-by essence must be used from kernel space for writing real-time device drivers.
-Those warnings are there to remind you that application code should run in
-user-space context instead.
-
-The reason for this is fully explained in the project Roadmap document, see
-"What Will Change With Xenomai 3": 
-"http://www.xenomai.org/index.php/Xenomai:Roadmap#What_Will_Change_With_Xenomai_3";.
-
-You may switch those warnings off by enabling the
-CONFIG_XENO_OPT_NOWARN_DEPRECATED option in your kernel configuration, but
-nevertheless, you have been WARNED.
-
-
-5.2. High latencies when transitioning from primary to secondary mode
----------------------------------------------------------------------
-
-Such transition requires to wake up the Linux task underlying your real-time
-thread when running in secondary mode, since the latter needs to leave the
-Xenomai domain for executing under the control of the regular Linux scheduler.
-Therefore, it all depends on the Linux kernel granularity, i.e. its ability to
-reach the next rescheduling point as soon as such wakeup has been requested.
-Additionally, the task wakeup request is performed from a virtual interrupt
-handler which has to be run from the Linux domain upon request from the Xenomai
-domain, so the time required to handle and dispatch this interrupt outside of
-any critical kernel section also needs to be accounted for. Even if the kernel
-granularity improves at each new release, there are still a few catches:
-
-  * Although the use of DMA might induce additional interrupt latency due to
-    bus bandwidth saturation, disabling it for disk I/O is a bad idea when
-    using mixed real-time modes. This is due to the fact that using PIO often
-    leads to lengthy non-preemptible sections of kernel code being run from
-    e.g. IDE drivers, from which pending real-time mode transitions could be
-    delayed. In the same vein, make sure that your IDE driver runs in unmasked
-    IRQ mode. In any case, a quick check using the "hdparm" tool will help:
-
-# hdparm -v /dev/hda
-
-/dev/hda:
- ...
- unmaskirq    =  1 (on)
- using_dma    =  1 (on)
- ...
-
-  * Even if your application does not directly request disk I/O, remember that
-    the kernel routinely performs housekeeping duties which do, like filesystem
-    journal updates or VM commits to the backing store, so latencies due to
-    improper disk settings may well trigger apparently randomly. Of course, if
-    your application only operates in primary mode during all of its time
-    critical duties, i.e. never request Linux syscalls, it will not be
-    adversely affected by DMA deactivation or IDE masking, since it will remain
-    in the Xenomai domain, and activities from such domain can preempt any
-    activity from the Linux domain, including disk drivers.
-
-
-5.3. Any Xenomai service fails with code -38 (ENOSYS)
------------------------------------------------------
-
-Possible reasons for this error are:
-
-  * you booted a kernel without Xenomai or I-pipe support, a kernel with I-pipe
-    and Xenomai support should have a /proc/ipipe/version and /proc/xenomai/
-    version files;
-  * the kernel you booted does not have the CONFIG_XENO_SKIN_* option enabled
-    for the skin you use, or CONFIG_XENO_OPT_PERVASIVE is disabled;
-  * Xenomai failed to start, check the "Xenomai or I-pipe error in the kernel
-    log" section;
-  * you are trying to run Xenomai user-space support compiled for x86_32 on an
-    x86_64 kernel.
-
-
-5.4. My application reserves a lot of memory
---------------------------------------------
-
-Your user-space application unexpectedly reserves a lot of virtual memory, as
-reported by "top" or /proc/<pid>/maps. Sometimes OOM situations even appear
-during runtime on systems with limited memory.
-
-The Xenomai tasks are underlaid by native POSIX threads, for which a huge
-default amount of stack space memory is reserved by the native POSIX support,
-usually 8MiB per thread, so the overall allocated space is about
-8MiB * +nr_threads+, which are likely to be locked using the mlockall()
-service, which in turn even commits such space to RAM.
-
-Unfortunately, this behaviour cannot be controlled by the "stacksize" parameter
-passed to the various thread creation routines, i.e. the latter is about
-limiting the addressable stack space on a per-thread basis, but does not affect
-the amount of stack memory initially reserved by the POSIX library. A
-work-around consists of setting a lower user-limit for initial stack
-allocation, like calling:
-
-ulimit -s <initial-size-in-kbytes>
-
-in your parent shell before running your application (defaults to 8192).
-
diff --git a/debian/rules b/debian/rules
index 5a7e5b1..07a4a19 100755
--- a/debian/rules
+++ b/debian/rules
@@ -79,7 +79,7 @@ install: build
 binary-indep: build install
        dh_testdir -i
        dh_testroot -i
-       dh_installdocs -i -A README.INSTALL README.APPLICATIONS MIGRATION 
TROUBLESHOOTING.COBALT TROUBLESHOOTING.MERCURY
+       dh_installdocs -i -A README
        dh_link -i
        dh_installchangelogs -i
        dh_strip -i
@@ -98,7 +98,7 @@ binary-arch: build install
        dh_testroot -s
        dh_installinit -s --name=xenomai
        dh_installman -s
-       dh_installdocs -s -A README.INSTALL README.APPLICATIONS MIGRATION 
TROUBLESHOOTING.COBALT TROUBLESHOOTING.MERCURY
+       dh_installdocs -s -A README
        dh_link -s
        dh_installchangelogs -s
        dh_strip -s
diff --git a/scripts/maint/resync-doc b/scripts/maint/resync-doc
index 457b357..a7d3eab 100755
--- a/scripts/maint/resync-doc
+++ b/scripts/maint/resync-doc
@@ -61,7 +61,6 @@ echo `cat tmp-dist/added_dirs tmp-dist/added_files`
 
 echo -n 'Copying prebuilt documentation to the source tree...'
 cp -aR tmp-dist/doc/prebuilt "$abs_srcdir"
-cp asciidoc/README.INSTALL.txt "$abs_srcdir"/../README.INSTALL
 echo done
 
 cd "$abs_srcdir"


_______________________________________________
Xenomai-git mailing list
Xenomai-git@xenomai.org
http://www.xenomai.org/mailman/listinfo/xenomai-git

Reply via email to