Commit d0d67d97 authored by Philippe Gerum's avatar Philippe Gerum

doc: prebuild

parent f9ed3db4
......@@ -1006,10 +1006,10 @@ of all timers from the registered Xenomai clocks.
</dd>
</dl></div>
<div class="paragraph"><p>There is no kernel-based time base management anymore with Xenomai
3.0-rc7. Functionally speaking, only the former <em>master</em> time base
3.0. 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 3.0-rc7 defines a built-in clock named <em>coreclk</em>, which has
<div class="paragraph"><p>Xenomai 3.0 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
......@@ -1722,23 +1722,25 @@ upon notification, which therefore applies to RTDM tasks as well.</p></div>
<div class="ulist"><ul>
<li>
<p>
<code>rtdm_task_set_period()</code> does not suspend the target task until the
first release point is reached. If a start date is specified, then
<code>rtdm_task_wait_period()</code> will apply the initial delay.
<code>rtdm_task_set_period()</code> now accepts a start date for the periodic
timeline. Zero can be passed to emulate the previous call form,
setting the first release point when the first period after the
current date elapses.
</p>
</li>
<li>
<p>
<code>rtdm_task_wait_period()</code> now copies back the count of overruns into
a user-provided variable if -ETIMEDOUT is returned. NULL can be passed
to emulate the previous call form, discarding this information.
</p>
</li>
<li>
<p>
Both <code>rtdm_task_set_period()</code> and <code>rtdm_task_wait_period()</code> may be
invoked over a Cobalt thread context.
</p>
</li>
</ul></div>
<div class="sidebarblock">
<div class="content">
<div class="title">Rationale</div>
<div class="paragraph"><p>A periodic RTDM task has to call <code>rtdm_task_wait_period()</code> from within
its work loop for sleeping until the next release point is
reached. Since waiting for the initial and subsequent release points
will most often happen at the same code location in the driver, the
semantics of <code>rtdm_task_set_period()</code> can be simplified so that only
<code>rtdm_task_wait_period()</code> may block the caller.</p></div>
</div></div>
<div class="ulist"><ul>
<li>
<p>
RTDM_EXECUTE_ATOMICALLY() is deprecated and will be phased out in
......@@ -2332,9 +2334,15 @@ kernel Cobalt environment.</td>
<div class="ulist"><ul>
<li>
<p>
Cobalt implements the following POSIX.1-2001 services not present in
Xenomai 2.x: <code>sched_setscheduler(2)</code>, <code>sched_getscheduler(2)</code>.
</p>
</li>
<li>
<p>
The <code>SCHED_FIFO</code>, <code>SCHED_RR</code>, <code>SCHED_SPORADIC</code> and <code>SCHED_TP</code>
classes now support up to 256 priority levels, instead of 99 as
previously with Xenomai 2.x. However, <code>sched_get_priority_max()</code>
previously with Xenomai 2.x. However, <code>sched_get_priority_max(2)</code>
still returns 99. Only the Cobalt extended call forms
(e.g. <code>pthread_attr_setschedparam_ex()</code>, <code>pthread_create_ex()</code>)
recognize these additional levels.
......@@ -2342,14 +2350,14 @@ The <code>SCHED_FIFO</code>, <code>SCHED_RR</code>, <code>SCHED_SPORADIC</code>
</li>
<li>
<p>
<code>sched_get_priority_min_ex()</code> and <code>sched_get_priority_max_ex()</code>
should be used for querying the static priority range of Cobalt
policies.
The new <code>sched_get_priority_min_ex()</code> and
<code>sched_get_priority_max_ex()</code> services should be used for querying
the static priority range of Cobalt policies.
</p>
</li>
<li>
<p>
<code>pthread_setschedparam()</code> may cause a secondary mode switch for the
<code>pthread_setschedparam(3)</code> may cause a secondary mode switch for the
caller, but will not cause any mode switch for the target thread
unlike with Xenomai 2.x.
</p>
......@@ -2357,11 +2365,11 @@ The <code>SCHED_FIFO</code>, <code>SCHED_RR</code>, <code>SCHED_SPORADIC</code>
Xenomai scheduler in sync, with respect to thread priorities, since
the former maintains a process-local priority cache for the threads
it knows about. Therefore, an explicit call to the the regular
<code>pthread_setschedparam()</code> shall be issued upon each priority change
<code>pthread_setschedparam(3)</code> shall be issued upon each priority change
Xenomai-wise, for maintaining consistency.</p></div>
<div class="paragraph"><p>In the Xenomai 2.x implementation, the thread being set a new
priority would receive a SIGSHADOW signal, triggering a call to
<code>pthread_setschedparam()</code> immediately.</p></div>
<code>pthread_setschedparam(3)</code> immediately.</p></div>
</li>
</ul></div>
<div class="sidebarblock">
......@@ -2371,10 +2379,10 @@ priority would receive a SIGSHADOW signal, triggering a call to
only be held in primary mode, in which case switching to secondary
mode for applying the priority change at any random location over a
signal handler may create a pathological issue. In addition,
<code>pthread_setschedparam()</code> is not async-safe, which makes the former
<code>pthread_setschedparam(3)</code> is not async-safe, which makes the former
method fragile.</p></div>
</div></div>
<div class="paragraph"><p>Conversely, a thread which calls <code>pthread_setschedparam()</code> does know
<div class="paragraph"><p>Conversely, a thread which calls <code>pthread_setschedparam(3)</code> does know
unambiguously whether the current calling context is safe for the
incurred migration.</p></div>
<div class="ulist"><ul>
......@@ -2397,7 +2405,7 @@ extent of the regular Linux SCHED_FIFO/RR priority range.</p></div>
class at priority level 20 in the Cobalt core, may be scheduled with
policy SCHED_FIFO/RR at priority 20, by the Linux kernel. The code
fragment below would set the scheduling parameters accordingly,
assuming the Cobalt version of <code>pthread_setschedparam()</code> is invoked:</p></div>
assuming the Cobalt version of <code>pthread_setschedparam(3)</code> is invoked:</p></div>
</li>
</ul></div>
<div class="listingblock">
......@@ -2435,7 +2443,7 @@ to each group, in accordance with its share.</p></div>
</li>
<li>
<p>
When called from primary mode, sched_yield() now delays the caller
When called from primary mode, sched_yield(2) now delays the caller
for a short while <strong>only in case</strong> no context switch happened as a
result of the manual round-robin. The delay ends next time the
regular Linux kernel switches tasks, or a kernel (virtual) tick has
......@@ -2449,7 +2457,7 @@ delayed for a while.</p></div>
<div class="sidebarblock">
<div class="content">
<div class="title">Rationale</div>
<div class="paragraph"><p>In most case, it is unwanted that sched_yield() does not cause any
<div class="paragraph"><p>In most case, it is unwanted that sched_yield(2) does not cause any
context switch, since this service is commonly used for implementing a
poor man&#8217;s cooperative scheduling. A typical use case involves a
Xenomai thread running in primary mode which needs to yield the CPU to
......@@ -2466,9 +2474,8 @@ out the delayed Xenomai thread indefinitely.</p></div>
<div class="ulist"><ul>
<li>
<p>
The default POSIX thread stack size was raised to
<code>PTHREAD_STACK_MIN * 4</code>. The minimum stack size enforced by the
<code>libcobalt</code> library is <code>PTHREAD_STACK_MIN + getpagesize()</code>.
The minimum and default stack size is set to <code>max(64k,
PTHREAD_STACK_MIN)</code>.
</p>
</li>
<li>
......@@ -2507,8 +2514,8 @@ condition variable).</td>
<div class="ulist"><ul>
<li>
<p>
With Cobalt, sem_wait(), sem_trywait(), sem_timedwait(), and
sem_post() have gained fast acquisition/release operations not
With Cobalt, sem_wait(3), sem_trywait(3), sem_timedwait(3), and
sem_post(3) have gained fast acquisition/release operations not
requiring any system call, unless a contention exists on the
resource. As a consequence, those services may not systematically
switch callers executing in relaxed mode to real-time mode, unlike
......@@ -2522,8 +2529,8 @@ With Cobalt, sem_wait(), sem_trywait(), sem_timedwait(), and
<div class="ulist"><ul>
<li>
<p>
In a <code>fork()</code> &#8594; <code>exec()</code> sequence, all Cobalt API objects created
by the child process before it calls <code>exec()</code> are automatically
In a <code>fork(2)</code> &#8594; <code>exec(2)</code> sequence, all Cobalt API objects created
by the child process before it calls <code>exec(2)</code> are automatically
flushed by the Xenomai core.
</p>