Installing Xenomai ================== 0. Introduction. ---------------- Starting with version 2.1, Xenomai follows a split source model, decoupling the kernel space support from the user-space libraries used in accessing the former. To this end, kernel and user-space Xenomai components are respectively available under the ksrc/ and src/ sub-trees. The ksrc/ sub-tree providing the kernel space support is seen as a built-in extension of the Linux kernel, and no more as a collection of separate out-of-tree modules. A direct benefit of such approach is the ability to build the Xenomai real-time subsystem statically into the target kernel, or as loadable modules as with earlier versions. therefore, the usual Linux kernel configuration process will be normally used to define the various settings for the Xenomai kernel components. Sections 1.1 and 1.2 document the installation process of this kernel space support. The src/ sub-tree contains the various user-space libraries and commands provided by the Xenomai framework. This tree can be built separately from the kernel support, even if the latter is absent from the build system. Section 1.3 documents the installation process of this user-space support. Finally, Xenomai build system also allows building a Xenomai patched kernel as part of the user space support compilation process. Section 1.4 documents this possibility. 1. Installation steps --------------------- 1.1 Preparing the target kernel ------------------------------- Xenomai provides a real-time sub-system 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= [--adeos=] [--arch=] --linux specifies the path of the target kernel source tree. Such kernel tree being configured or not makes no difference and is valid either way. --adeos specifies the path of the Adeos patch to apply against the kernel tree. Suitable patches are available with Xenomai under ksrc/arch//patches. This parameter can be omitted if Adeos has already been patched in or the script shall suggest an appropriate one. In any case, the script will not try to apply it again whenever a former patch is detected. --arch tells the script about the target architecture. If unspecified, the build system architecture is detected and suggested as a reasonable default. For instance, the following command would prepare the Linux tree located at /usr/src/linux-2.6.23-ipipe in order to include the Xenomai support: $ cd xenomai-2.4 $ scripts/prepare-kernel.sh --linux=/usr/src/linux-2.6.23-ipipe Note: The script will infer the location of the Xenomai kernel code from its own location within the Xenomai source tree. In other words, if /usr/src/xenomai-2.4/script/prepare-kernel.sh is executing, then Xenomai's kernel support available from /usr/src/xenomai-2.4/ksrc will be bound to the target kernel. 1.2 Configuring and building the target kernel ---------------------------------------------- Once the target kernel has been prepared, all Xenomai configuration options are available from the "Real-time subsystem" toplevel menu. There are several configure options that cause large latencies; they should be avoided. The TROUBLESHOOTING file identifies them and explains the issues with their use. Once configured, the kernel should be built as usual. If you want several different configs/builds at hand, you can reuse the same source by adding O=../build- to each make invocation. See section 2.2 for an example. In order to cross-compile the Linux kernel, pass an ARCH and CROSS_COMPILE variable on make command line. See sections 2.2, 2.3 and 2.4 for examples. 1.3 Building the user-space support ----------------------------------- A regular autoconf script is provided in order to prepare for building the user-space support. The options listed below can be passed to this script. Those options only affect the libraries compiled as part of Xenomai's user-space support, but in any case, they never impact the kernel-based support. 1.3.1 Feature conflict resolution --------------------------------- Because of the strong decoupling between the kernel and user-space build procedures, Xenomai needs to make sure that all user-space options selected at configuration time will be consistent with the actual support the runtime libraries will get from the target kernel. For instance, enabling TSC support in user-space for x86 albeit the kernel has been compiled with CONFIG_X86_TSC disabled would certainly lead to runtime problems if uncaught, since Xenomai and the application would not agree on the high precision clock to use for their timings. Furthermore, most of these issues cannot be probed for during compilation, because the target generally has different features than the host, even when theyre the same arch (ex 386 vs 686) In order to solve those potential issues, each Xenomai architecture port defines a set of critical features which is tested for consistency, each time a user-space application binds itself to a real-time interface in kernel space. Unresolvable conflicts are reported and the execution stops immediately in such a case. Options that need perfect matching between both sides are marked as "strong" in the following lists, others that may differ are marked as "weak". The way Xenomai deals with tolerated discrepancies is decided on a case-by-case basis, depending on the option considered. When not applicable, the binding type remains unspecified. For instance, a kernel providing SMP support can run either UP or SMP user-space applications since the SMP option's binding is weak. On the other hand, x86-based applications linked against Xenomai libraries which have been compiled with the x86-tsc option on, must run on a kernel built with CONFIG_X86_TSC set, since the x86-tsc option's binding is strong. 1.3.2 Generic configure options ------------------------------- NAME DESCRIPTION [BINDING,]DEFAULT(*) --prefix Installation directory /usr/xenomai --enable-debug Enable debug symbols (-g) disabled --enable-smp Enable SMP support weak,disabled 1.3.3 Arch-specific configure options ------------------------------------- NAME DESCRIPTION [BINDING,]DEFAULT(*) --enable-x86-sep Enable x86 SEP instructions strong,disabled for issuing syscalls. You will also need NPTL --enable-x86-tsc Enable x86 TSC for timings strong,enabled You must have TSC for this. --enable-arm-mach Select ARM machine for the none current build tree, check configure --help for a list of valid values. Passing this option is mandatory when compiling Xenomai for ARM --enable-arm-arch Define version of the target strong,"4" ARM core architecture. Using this option is only necessary if enable-arm-mach is integrator. --enable-arm-eabi Enable ARM EABI interface weak,disabled --enable-arm-tsc Enable ARM TSC emulation strong,enabled (*) Each option enabled by default can be forcibly disabled by passing --disable-