Commit dcd92e33 authored by Philippe Gerum's avatar Philippe Gerum

doc: prebuild

parent b7373564
......@@ -480,13 +480,20 @@ You may override the default root of the registry hierarchy by using the
--enable-async-cancel
Enables asynchronous cancellation of Xenomai threads created by the
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 enabled by default.
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.
......@@ -495,6 +502,11 @@ You may override the default root of the registry hierarchy by using the
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
......
......@@ -24,6 +24,9 @@ indifferently.
for which +xeno-config+ was generated. Possible output values are
+cobalt+ and +mercury+.
* +--ccld+ retrieves a C compiler command suitable for linking a
Xenomai 3.x application.
[[auto-init]]
* +--no-auto-init+ can be passed to disable automatic initialization
of the Copperplate library when the application process enters the
......@@ -32,8 +35,7 @@ indifferently.
routine manually, as part of its initialization process, _before_
any real-time service is invoked.
+xeno-config+ enables the auto-init feature by default for all
applications using APIs based on the Copperplate library.
+xeno-config+ enables the Copperplate auto-init feature by default.
- +--enable-x86-sep+ was renamed to +--enable-x86-vsyscall+ to fix a
misnomer. This option should be left enabled (default), unless
......@@ -163,13 +165,13 @@ obtained by reading +timer/coreclk.
- 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.
The gravity value for a Xenomai clock gives the amount of time by
which the next timer 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 is a static adjustment value, to account for the basic latency of
the target system for responding to external events. Such latency may
be introduced by hardware effects (e.g. bus or cache latency), or
software issues (e.g. code running with interrupts disabled).
The clock gravity management departs from Xenomai 2.x as follows:
......@@ -180,14 +182,40 @@ The clock gravity management departs from Xenomai 2.x as follows:
applying a global gravity value regardless of the activated context.
- in addition to the legacy +latency+ file which now reports the
_user_ timer gravity, i.e. used for timers activating user-space
threads, the full gravity triplet applied to timers running on the
core clock can be accessed by reading clock/coreclk.
_user_ timer gravity (in nanoseconds), i.e. used for timers
activating user-space threads, the full gravity triplet applied to
timers running on the core clock can be accessed by reading
clock/coreclk (also in nanoseconds).
- at reset, the _user_ gravity for the core clock now represents the
sum of the scheduling *and* hardware timer reprogramming time. This
departs from Xenomai 2.x for which only the former was accounted for
in the global gravity value.
sum of the scheduling *and* hardware timer reprogramming time as a
count of nanoseconds. This departs from Xenomai 2.x for which only the
former was accounted for as a global gravity value, regardless of the
target context for the timer.
The following command reports the current gravity triplet for the
target system, along with the setup information for the core timer:
--------------------------------------------
# cat xenomai/clock/coreclk
gravity: irq=848 kernel=8272 user=35303
devices: timer=decrementer, clock=timebase
status: on+watchdog
setup: 151
ticks: 220862243033
--------------------------------------------
Conversely, writing to this file manually changes the gravity values
of the Xenomai core clock:
------------------------------------------------------
/* change the user gravity (default) */
# echo 3000 > /proc/xenomai/clock/coreclck
/* change the IRQ gravity */
# echo 1000i > /proc/xenomai/clock/coreclck
/* change the user and kernel gravities */
# echo "2000u 1000k" > /proc/xenomai/clock/coreclck
------------------------------------------------------
- +interfaces+ was removed
......
......@@ -81,6 +81,20 @@ link:installing-xenomai-3-x[configuration switch]).
objects will be exported to +/mnt/xenomai/<session>.<pid>+,
despite the registry code was compiled in.
*--no-sanity*::
*--sanity*::
Turns off/on the sanity checks performed at application
startup by the Xenomai libraries. This option overrides the
--enable/disable-sanity options passed on the configuration
line when building the Xenomai libraries.
[TIP]
Passing *--no-sanity* allows running Xenomai libraries built
for a single-processor system (i.e. --disable-smp) on a SMP
system, assuming your application properly pins all threads
to a single CPU.
*--session=<label>*::
Name of the session the new process will be part of (or create
......
......@@ -507,22 +507,38 @@ does exist on the target kernel.
*--enable-async-cancel*::
Enables asynchronous cancellation of Xenomai threads created
by the real-time APIs, making provision to protect the Xenomai
implementation code accordingly.
Enables fully asynchronous cancellation of Xenomai threads
created by the real-time APIs, making provision to protect the
Xenomai implementation code accordingly.
[normal]
When disabled, Xenomai assumes that threads may exit due to
cancellation requests only when they reach cancellation points
(like system calls). Asynchronous cancellation is enabled by
default.
(like system calls). Asynchronous cancellation is disabled
by default.
[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: SMP support must be enabled in Xenomai libraries when the
[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
......
......@@ -780,6 +780,12 @@ Specifying <code>--[skin=]cobalt</code> or <code>--[skin=]posix</code> on the co
</li>
<li>
<p>
<code>--ccld</code> retrieves a C compiler command suitable for linking a
Xenomai 3.x application.
</p>
</li>
<li>
<p>
<code>--no-auto-init</code> can be passed to disable automatic initialization
of the Copperplate library when the application process enters the
<code>main()</code> routine. In such a case, the application code using any API
......@@ -789,8 +795,7 @@ Specifying <code>--[skin=]cobalt</code> or <code>--[skin=]posix</code> on the co
</p>
<div class="literalblock" id="auto-init">
<div class="content">
<pre><code>+xeno-config+ enables the auto-init feature by default for all
applications using APIs based on the Copperplate library.</code></pre>
<pre><code>+xeno-config+ enables the Copperplate auto-init feature by default.</code></pre>
</div></div>
</li>
</ul></div>
......@@ -908,10 +913,10 @@ Clocks
core, the <code>clock/</code> hierarchy was added, to reflect the current state
of all timers from the registered Xenomai clocks.</p></div>
<div class="paragraph"><p>There is no kernel-based time base management anymore with Xenomai
2.99.5. Functionally speaking, only the former <em>master</em> time base
2.99.6. Functionally speaking, only the former <em>master</em> time base
remains, periodic timing is now controlled locally from the Xenomai
libraries in user-space.</p></div>
<div class="paragraph"><p>Xenomai 2.99.5 defines a built-in clock named <em>coreclk</em>, which has
<div class="paragraph"><p>Xenomai 2.99.6 defines a built-in clock named <em>coreclk</em>, which has
the same properties than the former <em>master</em> time base available with
Xenomai 2.x (i.e. tickless with nanosecond resolution).</p></div>
<div class="paragraph"><p>The settings of existing clocks can be read from entries under the new
......@@ -937,12 +942,12 @@ Core clock gravity
</p>
</li>
</ul></div>
<div class="paragraph"><p>The gravity value for a Xenomai clock gives the amount of time
expressed in clock ticks, by which the next shot should be
anticipated.</p></div>
<div class="paragraph"><p>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).</p></div>
<div class="paragraph"><p>The gravity value for a Xenomai clock gives the amount of time by