Xenomai-forge Readme
Xenomai-forge 自述

This is Xenomai 3.x, the upcoming architecture of the Xenomai RTOS emulation system, which can run seamlessly as a dual kernel (i.e. like Xenomai 2.x, I-pipe based), or over mainline Linux kernels (likely PREEMPT-RT enabled though).
这是Xenomai 3.x，即将到来的Xenomai RTOS模拟系统的架构，它能够无缝运行如一个双内核（基于I-pipe技术的Xenomai 2.x），或者完全在Linux内核之上（启用PREEMPT-RT）。

This new architecture therefore exhibits two real-time cores, selected at build time. The dual kernel core inherited from the Xenomai 2.x architecture is nicknamed "Cobalt". The native linux core inherited from the former Xenomai/SOLO work is called "Mercury".
这个新架构呈现了两个实时核心，在编译阶段被选定。从Xenomai 2.x继承而来的双内核架构的核心被昵称为"Cobalt"。从Xenomai/SOLO继承而来的原生的Linux核心被称为"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 visiblechange.
这种神奇来自于"Copperplate"接口的介绍，它介于你的应用程序使用的实时API/模拟器和实时核心之间。应用程序能够被运行在任何环境，没有显而易见的改变。

This is experimental, work in progress, very much in flux code. The basic design won't change anymore though. Not all features we want to see there are available yet.
这是实验性的，渐近的，改进非常快的代码。基本的设计将不会被改变。并非我们想看到的所有的特征都已经具备了。

Performance-wise, we have no figure yet. However, this new design is known to significantly reduce the number of user/kernel transitions due to system calls on average compared to the 2.x architecture, which can't be bad.
我们还没有性能方面的路线图。然而，众所周知，这种新的设计显著降低了为了处理系统调用（和2.x架构的平均的比较）而导致用户/内核转换的次数，它不可能会是坏的。

Prerequisites  先决条件
=================
-- To run over the Cobalt core
--要运行在Cobalt核心

All like in the old days, as one used to bring up a Xenomai 2.x system, i.e:
象昔日使用Xenomai 2.x系统一样。

1. An interrupt pipeline patch which fits your hardware. Recent ones are readily available from the Xenomai source tree (see kernel/cobalt/arch/*/patches). All existing patches can be found at http://download.gna.org/adeos/patches/
1.一个匹配你的硬件的中断管道线的补丁。最新的补丁来自于Xenomai的源代码树(查看 kernel/cobalt/arch/*/patches)。所有存在的补丁能够在http://download.gna.org/adeos/patches/找到。
2. A working port of the Cobalt core to the target architecture. We intend to support the same set as available with Xenomai 2.6.x.
2.一个能够将Cobalt 核心移植到目标架构的移植案例。我们打算和Xenomai 2.6.x兼容。

-- To run over the Mercury core
--要运行在Mercury核心

1. A recent glibc featuring the NPTL thread library, with priority inheritance support for mutexes (PTHREAD_PRIO_INHERIT).
1.一个最近的glibc优先配备了NPTL线程库，具备支持互斥的优先级继承功能(PTHREAD_PRIO_INHERIT)。

2. Ideally, a real-time capable Linux kernel with the PREEMPT_RT support enabled. Non real-time kernels can be used too, likely for basic debugging tasks, and/or applications which do not have strict real-time requirements.
2.理想的情况下，一个具有PREEMPT_RT实时能力的Linux内核被启用。非实时内核也是可以被使用的，如为了
基本的调试任务，和（或）不需要严格实时要求的应用。

Compiling the Cobalt core  编译Cobalt核心
===============================

Same as Xenomai 2.6.x for the in-kernel part. Check out http://git.xenomai.org/?p=xenomai-head.git;a=blob;f=README.INSTALL;h=f9727c226b58e26b328a572f54712d034b8f8a65;hb=HEAD

Then, configure, build and install the user-space libraries and executables, passing --with-core=cobalt to the configure script. See below.
然后，传递--with-core=cobalt给配置脚本，配置，编译和安装用户空间库和执行文件。请看下面。

Compiling the Mercury core 编译Mercury核心
=================================

There is no Xenomai-specific kernel bits currently, until we have enabled the native RTDM support and drivers.  So for now, you just need to configure, build and install the user-space libraries and executables, passing --with-core=mercury to the configurescript. See below.
目前这里没有Xenomai指定内核点位，我们已经能够启动Native RTDM支持和驱动程序。因此在当前，你仅仅需要传递--with-core=cobalt给配置脚本，配置，编译和安装用户空间库和执行文件。请看下面。
Compiling the user-space libraries and executables (both cores) 编译用户空间库和可执行文件（双核心）
============================================================================
This code base has been autoconf-iscated, so building it is pretty simple, e.g.:
代码基础已经被自动配置，因此编译它是相当的简单。

$ mkdir build-dir
$ cd build-dir
$ ../xenomai-forge/configure --with-core=<cobalt|mercury> <other-options>
$ make
$ make install [DESTDIR=/staging/dir]


Where <other-options> may be any standard autoconf switch, such as:
这里<other-options>可以是任何标准autoconf开关，诸如：

--prefix=<dir>


To specify the runtime path for the installation of libraries, include files, scripts and executables. "make install" installs these files to ${DESTDIR}/<dir>.


This directory defaults to /usr/xenomai.


or Xenomai-specific knobs:


--enable-debug[=full]

This switch will enable debug mode, causing debug symbols to be compiled in the libraries and executables, passing the -g flag to the compiler to get debug symbols. When enabled, this switch also causes the __XENO_DEBUG__ macro to be defined, for both theXenomai core and the applications getting their C
compilation flags from the xeno-config script (i.e. xeno-config --cflags).  Debug mode is off by default.


If the full debug level is specified along with this switch, -O0 is passed to the compiler, to disable the optimizer. In
addition, the macro __XENO_DEBUG_FULL__ is also defined.


Over the Mercury core, enabling debug mode 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.


--enable-assert

A number of debug assertion statements are wired into the  Xenomai core, which aim at checking the internal consistency of the emulation system during runtime (see man assert(3)). Passing --disable-assert to the configure script disables built-in assertions.Assertions are enabled by default.


--enable-pshared


Enable shared multi-processing. When enabled, this option  allows multiple processes to share real-time objects
(e.g. tasks, semaphores).


--enable-registry


Some 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, which must be available on the target  system. Building the Xenomai core with the registry support  requires the FUSEdevelopment libraries to be installed on the  build system.


When this option is enabled, the emulator creates a file  hierachy under /mnt/xenomai/<pid> (by default), where you can  access the internal state of the active real-time  objects. E.g. looking at the properties of a VxWorks task
could be done as follows:


$ cat /mnt/xenomai/12656/vxworks/tasks/windTask 
name       = windTask
errno      = 0
status     = ready
priority   = 70
lock_depth = 0


You may override the default mount point of the registry hierarchy by using the --registry-mountpt runtime option (see below).


NOTE: the FUSE-based registry support is still in its early  stage, and only a few objects are currently exported, only by  the VxWorks API when running over the Mercury core. This is  work in progress, so don't expect too much yet.


When running over the Cobalt core however, the /proc/xenomai  interface is available for inspecting the core system state  (i.e. nucleus and RTDM), like with Xenomai 2.x.


--enable-lores-clock


Enable low resolution clock. By default, both cores are built  with support for tick-based timing. If you don't actually
require such support and only use tickless real-time APIs,  then you can use --disable-lores-clock to optimize out this  support.


--enable-clock-monotonic-raw


The Xenomai core 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: Cobalt implements CLOCK_MONOTONIC_RAW, so this clock is  turned on by default when building with
--with-core=cobalt. However, the Mercury core turns this off  by default, since we don't know in advance whether this  feature exists on the target kernel.


Compiling an application 编译一个应用程序
================================


Like with Xenomai 2.x, you should use the xeno-config script to get the proper compilation and linker flags related to Xenomai, for building your application, for whichever core. Here is a Makefile fragment fetching the compilation and linker flags for buildinga VxWorks-based application, over the Xenomai emulator:


XENO_CONFIG := /usr/xenomai/bin/xeno-config
CFLAGS := $(shell $(XENO_CONFIG) --skin=vxworks --cflags)
LDFLAGS := $(shell $(XENO_CONFIG) --skin=vxworks --ldflags)


Running a Xenomai 3.x application 运行一个Xenomai 3.x应用程序
===============================================


For Cobalt, you need Xenomai's Cobalt dual kernel bits built in the target kernel. The build procedure is identical to Xenomai 2.x.
对于Cobalt，你需要被编译进目标内核的Xenomai's Cobalt 双内核点位。构建过程是和Xenomai 2.x相同的。


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 ideally complete preemption (PREEMPT_RT) ifyour application requires short and bounded latencies.
对于Mercury，你不再需要Xenomai指定内核支持，由于你的主机Linux内核已经提供了。如果你的应用程序需要短期的和有限延迟性能，你的内核至少需要提供高精度定时器支持(CONFIG_HIGH_RES_TIMERS)，和理想情况下完全抢占(PREEMPT_RT) 。


An application recognises a set of options that may be passed on the command line, namely:


--<api>-clock-resolution=<ns>


The clock resolution available with the API, given as a count of nano-seconds, i.e. HZ=(1000000000 / ns). <api> is the name of one of the existing Xenomai 3.x APIs your application can be linked against, e.g. psos, vxworks or alchemy. When your applicationcombines multiple APIs, you can pass several clock-resolution switches to set them all.

The default value depends on the API.


--mem-pool-size=<kb>


The initial size in Kilobytes of the main memory pool. This option only makes sense when the TLSF allocator is being used (i.e. --enable-debug is not specified when compiling the Xenomai core). This is only a hint, since TLSF will increase the main pool sizedynamically as needed, if needed. However, this option may be used to pre-allocate the specified amount of memory to the application process, thus avoiding costly system calls to extend the data segment of such process while operating in time critical mode.


--no-mlock


Tells the Xenomai core not to lock the process memory while initializing. The application will have to handle this task when and how it sees fit, in order to avoid the extra latency induced by virtual memory paging.  Otherwise,
mlockall(MCL_CURRENT | MCL_FUTURE) is automatically invoked by the Xenomai core as part of the emulator initialization duties.


--registry-mountpt=<path>


Tells the emulator to mount the object registry over the given path, instead of /mnt/xenomai/<pid> by default (see the --enable-registry switch from the build time options).


--no-registry


This switch disables registry support at runtime. No real-time objects will be exported to /mnt/xenomai/<pid>, despite the registry code has been compiled in.


--session=<name>


Name of the session the new process will be part of (or create if not present). This is only useful when --enable-pshared was passed at build time, to allow multiple processes to operate on remote objects. e.g. allowing a process to post a semaphore createdby another process within the same session. This is done using a common heap area, shared by all processes within the same session.


--reset


Force removal of an older session. This only works if the process which created the shared heap for the former session has exited, otherwise an error is raised.


--cpu-affinity=<cpu[,cpu]...>


Set CPU affinity of threads created by the Xenomai core within the new process.


--enable-async-cancel
Allow threads to be cancelled asynchronously. When disabled, threads are deleted only when they reach specific cancellation points (like system calls). Defaults to enabled.


Available emulators/APIs  可用的模拟器/API
================================

VxWorks：
See lib/vxworks/README.
VxWorks is a registered trademark of Wind River Systems, Inc (http://www.windriver.com).
VxWorks：
查看lib/vxworks/README。
VxWorks是风河系统公司的注册商标 (http://www.windriver.com)。

pSOS：
See lib/psos/README.
pSOS is a registered trademark of Wind River Systems, Inc (http://www.windriver.com).
pSOS：
查看lib/psos/README。
pSOS是风河系统公司的注册商标 (http://www.windriver.com)。

Alchemy：
This is a re-implementation of Xenomai's former "native" API, fully rebased on the new RTOS emulation core. This is work in progress.
Alchemy：
这是一个重新执行的Xenomai形式的Native API，完全基于新的RTOS模拟核心。这是正在进行的工作。

Wed Sep 21 11:54:54 CEST 2011
by <rpm@xenomai.org>