Module: xenomai-3
Branch: arm64
Commit: b05639b62050e4b305d075bb7e0d546e63bf7a20
URL:    
http://git.xenomai.org/?p=xenomai-3.git;a=commit;h=b05639b62050e4b305d075bb7e0d546e63bf7a20

Author: Philippe Gerum <r...@xenomai.org>
Date:   Wed Sep 30 20:49:37 2015 +0200

lib/cobalt: assorted documentation fixes

---

 doc/asciidoc/MIGRATION.adoc              |  109 +++++++++--------
 doc/asciidoc/TROUBLESHOOTING.COBALT.adoc |   40 ++++---
 kernel/cobalt/rtdm/drvlib.c              |    2 +-
 lib/cobalt/clock.c                       |    4 +-
 lib/cobalt/cond.c                        |   23 ++--
 lib/cobalt/init.c                        |   12 +-
 lib/cobalt/internal.c                    |    6 +-
 lib/cobalt/mq.c                          |   14 +--
 lib/cobalt/mutex.c                       |   22 ++--
 lib/cobalt/sched.c                       |   80 ++++---------
 lib/cobalt/semaphore.c                   |   15 ++-
 lib/cobalt/sigshadow.c                   |    2 +-
 lib/cobalt/thread.c                      |  192 +++++++++++-------------------
 lib/cobalt/timer.c                       |    3 +-
 14 files changed, 227 insertions(+), 297 deletions(-)

diff --git a/doc/asciidoc/MIGRATION.adoc b/doc/asciidoc/MIGRATION.adoc
index 4cb8836..62aaae3 100644
--- a/doc/asciidoc/MIGRATION.adoc
+++ b/doc/asciidoc/MIGRATION.adoc
@@ -755,19 +755,17 @@ kernel requires kernel threads to exit at their earliest 
convenience
 upon notification, which therefore applies to RTDM tasks as well.
 **********************************************************************
 
-- +rtdm_task_set_period()+ does not suspend the target task until the
-first release point is reached. If a start date is specified, then
-+rtdm_task_wait_period()+ will apply the initial delay.
+- +rtdm_task_set_period()+ 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.
 
-.Rationale
-**********************************************************************
-A periodic RTDM task has to call +rtdm_task_wait_period()+ 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 +rtdm_task_set_period()+ can be simplified so that only
-+rtdm_task_wait_period()+ may block the caller.
-**********************************************************************
+- +rtdm_task_wait_period()+ 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.
+
+- Both +rtdm_task_set_period()+ and +rtdm_task_wait_period()+ may be
+  invoked over a Cobalt thread context.
 
 - RTDM_EXECUTE_ATOMICALLY() is deprecated and will be phased out in
   the next release. Drivers should prefer the newly introduced RTDM
@@ -1208,18 +1206,21 @@ kernel Cobalt environment.
 
 === Scheduling ===
 
+- Cobalt implements the following POSIX.1-2001 services not present in
+  Xenomai 2.x: +sched_setscheduler(2)+, +sched_getscheduler(2)+.
+
 - The +SCHED_FIFO+, +SCHED_RR+, +SCHED_SPORADIC+ and +SCHED_TP+
   classes now support up to 256 priority levels, instead of 99 as
-  previously with Xenomai 2.x. However, +sched_get_priority_max()+
+  previously with Xenomai 2.x. However, +sched_get_priority_max(2)+
   still returns 99. Only the Cobalt extended call forms
   (e.g. +pthread_attr_setschedparam_ex()+, +pthread_create_ex()+)
   recognize these additional levels.
 
-- +sched_get_priority_min_ex()+ and +sched_get_priority_max_ex()+
-  should be used for querying the static priority range of Cobalt
-  policies.
+- The new +sched_get_priority_min_ex()+ and
+  +sched_get_priority_max_ex()+ services should be used for querying
+  the static priority range of Cobalt policies.
 
-- `pthread_setschedparam()` may cause a secondary mode switch for the
+- `pthread_setschedparam(3)` 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.
 
@@ -1228,13 +1229,13 @@ kernel Cobalt environment.
   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
-  `pthread_setschedparam()` shall be issued upon each priority change
+  `pthread_setschedparam(3)` shall be issued upon each priority change
   Xenomai-wise, for maintaining consistency.
 
 [normal]
   In the Xenomai 2.x implementation, the thread being set a new
   priority would receive a SIGSHADOW signal, triggering a call to
-  `pthread_setschedparam()` immediately.
+  `pthread_setschedparam(3)` immediately.
 
 .Rationale
 **********************************************************************
@@ -1242,12 +1243,12 @@ The target Xenomai thread may hold a mutex or any 
resource which may
 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,
-`pthread_setschedparam()` is not async-safe, which makes the former
+`pthread_setschedparam(3)` is not async-safe, which makes the former
 method fragile.
 **********************************************************************
 
 [normal]
-  Conversely, a thread which calls +pthread_setschedparam()+ does know
+  Conversely, a thread which calls +pthread_setschedparam(3)+ does know
   unambiguously whether the current calling context is safe for the
   incurred migration.
 
@@ -1273,7 +1274,7 @@ method fragile.
   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 +pthread_setschedparam()+ is invoked:
+  assuming the Cobalt version of +pthread_setschedparam(3)+ is invoked:
 
 ----------------------------------------------------------------------
        struct sched_param param = {
@@ -1312,7 +1313,7 @@ method fragile.
   quota interval starts. At this point, a new runtime budget is given
   to each group, in accordance with its share.
 
-- 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 *only in case* 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
@@ -1325,7 +1326,7 @@ method fragile.
 
 .Rationale
 **********************************************************************
-In most case, it is unwanted that sched_yield() does not cause any
+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's cooperative scheduling. A typical use case involves a
 Xenomai thread running in primary mode which needs to yield the CPU to
@@ -1339,9 +1340,8 @@ out the delayed Xenomai thread indefinitely.
 
 === Thread management ===
 
-- The default POSIX thread stack size was raised to
-  `PTHREAD_STACK_MIN * 4`. The minimum stack size enforced by the
-  +libcobalt+ library is `PTHREAD_STACK_MIN + getpagesize()`.
+- The minimum and default stack size is set to `max(64k,
+  PTHREAD_STACK_MIN)`.
 
 - pthread_set_name_np() has been renamed to pthread_setname_np() with
   the same arguments, to conform with the GNU extension equivalent.
@@ -1365,8 +1365,8 @@ condition variable).
 
 === Semaphores ===
 
-- 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
@@ -1374,8 +1374,8 @@ condition variable).
 
 === Process management ===
 
-- In a +fork()+ -> +exec()+ sequence, all Cobalt API objects created
-  by the child process before it calls +exec()+ are automatically
+- In a +fork(2)+ -> +exec(2)+ sequence, all Cobalt API objects created
+  by the child process before it calls +exec(2)+ are automatically
   flushed by the Xenomai core.
 
 [[real-time-signals]]
@@ -1384,9 +1384,9 @@ condition variable).
 - Support for Xenomai real-time signals is available.
 
 [normal]
-Cobalt replacements for +sigwait()+, +sigwaitinfo()+,
-+sigtimedwait()+, +sigqueue()+ and +kill()+ are
-available. +pthread_kill()+ was changed to send thread-directed
+Cobalt replacements for +sigwait(3)+, +sigwaitinfo(2)+,
++sigtimedwait(2)+, +sigqueue(3)+ and +kill(2)+ are
+available. +pthread_kill(3)+ was changed to send thread-directed
 Xenomai signals (instead of regular Linux signals).
 
 [normal]
@@ -1407,24 +1407,24 @@ COBALT_DELAYMAX is defined as the maximum number of 
overruns which can
 be reported by the Cobalt core in the siginfo.si_overrun field, for
 any signal.
 
-- +kill()+ supports group signaling.
+- Cobalt's +kill(2)+ implementation supports group signaling.
 
 [normal]
-Cobalt's implementation of kill() behaves identically to the regular
+Cobalt's implementation of kill(2) behaves identically to the regular
 system call for non thread-directed signals (i.e. pid <= 0). In this
 case, the caller switches to secondary mode.
 
 [normal]
 Otherwise, Cobalt first attempts to deliver a thread-directed signal
 to the thread whose kernel TID matches the given process id. If this
-thread is not waiting for signals at the time of the call, kill() then
+thread is not waiting for signals at the time of the call, kill(2) then
 attempts to deliver the signal to a thread from the same process,
 which currently waits for a signal.
 
-- +pthread_kill()+ is a conforming call.
+- +pthread_kill(3)+ is a conforming call.
 
 [normal]
-When Cobalt's replacement for +pthread_kill()+ is invoked, a
+When Cobalt's replacement for +pthread_kill(3)+ is invoked, a
 Xenomai-enabled caller is automatically switched to primary mode on
 its way to sending the signal, under the control of the real-time
 co-kernel. Otherwise, the caller keeps running under the control of
@@ -1432,7 +1432,7 @@ the regular Linux kernel.
 
 [normal]
 This behavior also applies to the new Cobalt-based replacement for the
-+kill()+ system call.
++kill(2)+ system call.
 
 === Timers ===
 
@@ -1442,17 +1442,17 @@ This behavior also applies to the new Cobalt-based 
replacement for the
 - If the thread signaled by a POSIX timer exits, the timer is
   automatically stopped at the first subsequent timeout which fails
   sending the notification. The timer lingers until it is deleted by a
-  call to +timer_delete()+ or when the process exits, whichever comes
+  call to +timer_delete(2)+ or when the process exits, whichever comes
   first.
 
-- timer_settime() may be called from a regular thread (i.e. which is
+- timer_settime(2) may be called from a regular thread (i.e. which is
   not Xenomai-enabled).
 
 - EPERM is not returned anymore by POSIX timer calls. EINVAL is
   substituted in the corresponding situation.
 
-- Cobalt replacements for +timerfd_create()+, +timerfd_settime()+ and
-+timerfd_gettime()+ have been introduced. The implementation delivers
+- Cobalt replacements for +timerfd_create(2)+, +timerfd_settime(2)+ and
++timerfd_gettime(2)+ have been introduced. The implementation delivers
 I/O notifications to RTDM file descriptors upon Cobalt-originated
 real-time signals.
 
@@ -1464,17 +1464,17 @@ removed from the API.
 With the introduction of services to support real-time signals, those
 two non-portable calls have become redundant. Instead, Cobalt-based
 applications should set up a periodic timer using the
-`timer_create()`+`timer_settime()` call pair, then wait for release
-points via `sigwaitinfo()`. Overruns can be detected by looking at the
+`timer_create(2)`+`timer_settime(2)` call pair, then wait for release
+points via `sigwaitinfo(2)`. Overruns can be detected by looking at the
 siginfo.si_overrun field.
     
 Alternatively, applications may obtain a file descriptor referring to
-a Cobalt timer via the `timerfd()` call, and `read()` from it to wait
+a Cobalt timer via the `timerfd_create(2)` call, and `read(2)` from it to wait
 for timeouts.
     
 In addition, applications may include a timer in a synchronous
 multiplexing operation involving other event sources, by passing a
-file descriptor returned by the `timerfd()` service to a `select()`
+file descriptor returned by the `timerfd_create(2)` service to a `select(2)`
 call.
 **********************************************************************
 
@@ -1494,10 +1494,10 @@ is subject to change with ABI revisions.
 
 === Message queues ===
 
-- +mq_open()+ default attributes align on the regular kernel values,
+- +mq_open(3)+ default attributes align on the regular kernel values,
   i.e. 10 msg x 8192 bytes (instead of 128 x 128).
 
-- +mq_send()+ now enforces a maximum priority value for messages
+- +mq_send(3)+ now enforces a maximum priority value for messages
   (32768).
 
 === POSIX I/O services ===
@@ -1540,8 +1540,13 @@ receipts, as explained <<userirqtip,here>>.
 
 === I/O regions ===
 
-- The RT_IOREGION API is gone. I/O memory resources should
-  be controlled from a RTDM driver instead.
+- The RT_IOREGION API is gone. I/O memory resources should be
+  controlled from a RTDM driver instead.
+
+[TIP]
+<<userirqtip,UDD>> provides a simple way to implement mini-drivers
+exposing any kind of memory regions to applications in user-space, via
+Cobalt's mmap(2) call.
 
 === Timing services ===
 
diff --git a/doc/asciidoc/TROUBLESHOOTING.COBALT.adoc 
b/doc/asciidoc/TROUBLESHOOTING.COBALT.adoc
index f750957..6b7910c 100644
--- a/doc/asciidoc/TROUBLESHOOTING.COBALT.adoc
+++ b/doc/asciidoc/TROUBLESHOOTING.COBALT.adoc
@@ -184,26 +184,34 @@ Same as below:
 
 === ABI mismatch
 
+The ABI concerned by this message is the system call binary interface
+between the Xenomai libraries and the real-time kernel services it
+invokes (e.g. +libcobalt+ and the Cobalt kernel with Xenomai
+3.x). This ABI may evolve over time, only between major Xenomai
+releases or testing candidate releases (i.e. -rc series) though. When
+this happens, the ABI level required by the application linked against
+Xenomai libraries may not match the ABI exposed by the Xenomai
+co-kernel implementation on the target machine, which is the situation
+this message reports.
+
+To fix this issue, just make sure to rebuild both the Xenomai kernel
+support and the user-space binaries for your target system. If however
+you did install the appropriate Xenomai binaries on your target
+system, chances are that stale files from a previous Xenomai
+installation still exist on your system, causing the mismatch.
+
 Each major Xenomai release (e.g. 2.1.x, 2.2.x ... 2.6.x, 3.0.x ...)
-defines a kernel/user ABI, which remains stable across minor update
-releases (e.g. 2.6.0 -> 2.6.1). This guarantee makes partial updates
+defines such kernel/user ABI, which remains stable across minor update
+releases (e.g. 2.6.0 -> 2.6.4). This guarantee makes partial updates
 possible with production systems (i.e. kernel and/or user support).
-
-For instance, any application built over the Xenomai 2.6.0 libraries
-can run over a Xenomai 2.6.3 kernel support, and conversely.
-
-However, it is not possible to mix kernel and user-space supports from
-different major releases.
+For instance, any application built over the Xenomai 2.6.0 binaries
+can run over a Xenomai 2.6.4 kernel support, and conversely.
 
 [TIP]
-A common source of error is running a kernel with support from the
-Xenomai 2.6.x series, on a system with pre-installed Xenomai libraries
-from the 2.5.x series, shipped with a Debian-based Linux distribution
-(notably Ubuntu), which won't work as the two series have different
-ABIs.  If however you did install the correct Xenomai user-space
-support on your target system, chances are that stale files from a
-previous Xenomai installation still exist on your system, causing the
-mismatch.
+Debian-based distributions (notably Ubuntu) may ship with
+pre-installed Xenomai libraries. Make sure that these files don't get
+in the way if you plan to install a more recent Xenomai kernel
+support.
 
 === <program>: not found
 
diff --git a/kernel/cobalt/rtdm/drvlib.c b/kernel/cobalt/rtdm/drvlib.c
index 05af769..81a59c1 100644
--- a/kernel/cobalt/rtdm/drvlib.c
+++ b/kernel/cobalt/rtdm/drvlib.c
@@ -226,7 +226,7 @@ int rtdm_task_set_period(rtdm_task_t *task, nanosecs_abs_t 
start_date,
 /**
  * @brief Wait on next real-time task period
  *
- * @param[in] overrun_r Address of a long word receiving the count of
+ * @param[in] overruns_r Address of a long word receiving the count of
  * overruns if -ETIMEDOUT is returned, or NULL if the caller don't
  * need that information.
  *
diff --git a/lib/cobalt/clock.c b/lib/cobalt/clock.c
index d17ea56..3fe6658 100644
--- a/lib/cobalt/clock.c
+++ b/lib/cobalt/clock.c
@@ -52,7 +52,7 @@
  *
  * CLOCK_MONOTONIC_RAW is Linux-specific, and provides monotonic time
  * values from a hardware timer which is not adjusted by NTP. This is
- * strictly equivalent to CLOCK_MONOTONIC with Xenomai, which is not
+ * strictly equivalent to CLOCK_MONOTONIC with Cobalt, which is not
  * NTP adjusted either.
  *
  * In addition, external clocks can be dynamically registered using
@@ -160,7 +160,7 @@ static int __do_clock_host_realtime(struct timespec *ts)
  *   precision independent from the system clock tick duration.
  * - CLOCK_HOST_REALTIME, the clock value as seen by the host, typically
  *   Linux. Resolution and precision depend on the host, but it is guaranteed
- *   that both, host and Xenomai, see the same information.
+ *   that both, host and Cobalt, see the same information.
  *
  * @param clock_id clock identifier, either CLOCK_REALTIME, CLOCK_MONOTONIC,
  *        or CLOCK_HOST_REALTIME;
diff --git a/lib/cobalt/cond.c b/lib/cobalt/cond.c
index ba1fada..bb9e84c 100644
--- a/lib/cobalt/cond.c
+++ b/lib/cobalt/cond.c
@@ -88,10 +88,9 @@ void cobalt_default_condattr_init(void)
  * @fn int pthread_cond_init(pthread_cond_t *cond, const pthread_condattr_t 
*attr)
  * @brief Initialize a condition variable
  *
- * This service initializes the condition variable @a cond, using the condition
- * variable attributes object @a attr. If @a attr is @a NULL or this service is
- * called from user-space, default attributes are used (see
- * pthread_condattr_init()).
+ * This service initializes the condition variable @a cond, using the
+ * condition variable attributes object @a attr. If @a attr is @a
+ * NULL, default attributes are used (see pthread_condattr_init()).
  *
  * @param cond the condition variable to be initialized;
  *
@@ -102,7 +101,7 @@ void cobalt_default_condattr_init(void)
  * - EINVAL, the condition variable attributes object @a attr is invalid or
  *   uninitialized;
  * - EBUSY, the condition variable @a cond was already initialized;
- * - ENOMEM, insufficient memory exists in the system heap to initialize the
+ * - ENOMEM, insufficient memory available from the system heap to initialize 
the
  *   condition variable, increase CONFIG_XENO_OPT_SYS_HEAPSZ.
  *
  * @see
@@ -223,10 +222,10 @@ static int __attribute__((cold)) 
cobalt_cond_autoinit(pthread_cond_t *cond)
  * calls this service specifying @a cnd as a condition variable but another
  * mutex than @a mx, this service returns immediately with the EINVAL status.
  *
- * This service is a cancellation point for Xenomai POSIX skin threads
- * (created with the pthread_create() service). When such a thread is cancelled
- * while blocked in a call to this service, the mutex @a mx is re-acquired
- * before the cancellation cleanup handlers are called.
+ * This service is a cancellation point for Cobalt threads (created
+ * with the pthread_create() service). When such a thread is cancelled
+ * while blocked in a call to this service, the mutex @a mx is
+ * re-acquired before the cancellation cleanup handlers are called.
  *
  * @param cond the condition variable to wait for;
  *
@@ -571,7 +570,7 @@ int pthread_condattr_destroy(pthread_condattr_t * attr);
  * This service stores, at the address @a clk_id, the value of the @a clock
  * attribute in the condition variable attributes object @a attr.
  *
- * See pthread_cond_timedwait() documentation for a description of the effect 
of
+ * See pthread_cond_timedwait() for a description of the effect of
  * this attribute on a condition variable. The clock ID returned is @a
  * CLOCK_REALTIME or @a CLOCK_MONOTONIC.
  *
@@ -598,8 +597,8 @@ int pthread_condattr_getclock(const pthread_condattr_t * 
attr,
  * This service set the @a clock attribute of the condition variable attributes
  * object @a attr.
  *
- * See pthread_cond_timedwait() documentation for a description of the effect
- * of this attribute on a condition variable.
+ * See pthread_cond_timedwait() for a description of the effect of
+ * this attribute on a condition variable.
  *
  * @param attr an initialized condition variable attributes object,
  *
diff --git a/lib/cobalt/init.c b/lib/cobalt/init.c
index 8a48428..2910f6e 100644
--- a/lib/cobalt/init.c
+++ b/lib/cobalt/init.c
@@ -203,12 +203,12 @@ int cobalt_init(void)
        }
 
        /*
-        * Switch the main thread to a Xenomai shadow.
-        * __cobalt_main_prio might have been overriden by
-        * some compilation unit which has been linked in, to force
-        * the scheduling parameters. Otherwise, the current policy
-        * and priority are reused, for declaring the thread to the
-        * Xenomai scheduler.
+        * Turn the main thread into a Cobalt thread.
+        * __cobalt_main_prio might have been overriden by some
+        * compilation unit which has been linked in, to force the
+        * scheduling parameters. Otherwise, the current policy and
+        * priority are reused, for declaring the thread to the
+        * Cobalt scheduler.
         *
         * SCHED_FIFO is assumed for __cobalt_main_prio > 0.
         */
diff --git a/lib/cobalt/internal.c b/lib/cobalt/internal.c
index 62ecb4a..210d259 100644
--- a/lib/cobalt/internal.c
+++ b/lib/cobalt/internal.c
@@ -93,8 +93,8 @@ int cobalt_thread_join(pthread_t thread)
         * -EBUSY denotes a multiple join for several threads in
         * parallel to the same target.
         *
-        * -EPERM may be received because the current context is not a
-        * Xenomai thread.
+        * -EPERM may be received because the caller is not a
+        * Cobalt thread.
         *
         * -EINVAL is received in case the target is not a joinable
         * thread (i.e. detached).
@@ -186,7 +186,7 @@ int cobalt_monitor_enter(cobalt_monitor_t *mon)
        /*
         * Assumptions on entry:
         *
-        * - this is a Xenomai shadow (caller checked this).
+        * - this is a Cobalt thread (caller checked this).
         * - no recursive entry/locking.
         */
 
diff --git a/lib/cobalt/mq.c b/lib/cobalt/mq.c
index a1aed3b..177c903 100644
--- a/lib/cobalt/mq.c
+++ b/lib/cobalt/mq.c
@@ -42,8 +42,7 @@
 /**
  * @brief Open a message queue
  *
- * This service establishes a connection between the message queue named @a 
name
- * and the calling context (kernel-space as a whole, or user-space process).
+ * This service opens the message queue named @a name.
  *
  * One of the following values should be set in @a oflags:
  * - O_RDONLY, meaning that the returned queue descriptor may only be used for
@@ -88,8 +87,8 @@
  *   message queue already exists;
  * - ENOENT, the bit @a O_CREAT is not set in @a oflags and the message queue
  *   does not exist;
- * - ENOSPC, allocation of system memory failed, or insufficient memory exists
- *   in the system heap to create the queue, try increasing
+ * - ENOSPC, allocation of system memory failed, or insufficient memory 
available
+ *   from the system heap to create the queue, try increasing
  *   CONFIG_XENO_OPT_SYS_HEAPSZ;
  * - EPERM, attempting to create a message queue from an invalid context;
  * - EINVAL, the @a attr argument is invalid;
@@ -528,17 +527,14 @@ COBALT_IMPL(ssize_t, mq_timedreceive, (mqd_t q,
  * blocked in call to mq_receive() or mq_timedreceive(). After the
  * notification, the thread is unregistered.
  *
- * If @a evp is @a NULL or the @a sigev_notify member is SIGEV_NONE, the 
current
- * thread is unregistered.
+ * If @a evp is @a NULL or the @a sigev_notify member is SIGEV_NONE,
+ * the current thread is unregistered.
  *
  * Only one thread may be registered at a time.
  *
  * If the current thread is not a Cobalt thread (created with
  * pthread_create()), this service fails.
  *
- * Note that signals sent to user-space Cobalt threads will cause
- * them to switch to secondary mode.
- *
  * @param mqd message queue descriptor;
  *
  * @param evp pointer to an event notification structure.
diff --git a/lib/cobalt/mutex.c b/lib/cobalt/mutex.c
index 2f84bde..b2d7b65 100644
--- a/lib/cobalt/mutex.c
+++ b/lib/cobalt/mutex.c
@@ -77,11 +77,11 @@ void cobalt_default_mutexattr_init(void)
  * @return an error number if:
  * - EINVAL, the mutex attributes object @a attr is invalid or uninitialized;
  * - EBUSY, the mutex @a mx was already initialized;
- * - ENOMEM, insufficient memory exists in the system heap to initialize the
+ * - ENOMEM, insufficient memory available from the system heap to initialize 
the
  *   mutex, increase CONFIG_XENO_OPT_SYS_HEAPSZ.
- * - EAGAIN, insufficient memory exists in the semaphore heap to initialize the
+ * - EAGAIN, insufficient memory available to initialize the
  *   mutex, increase CONFIG_XENO_OPT_SHARED_HEAPSZ for a process-shared
- *   mutex, or CONFG_XENO_OPT_PRIVATE_HEAPSZ for a process-private mutex.
+ *   mutex, or CONFIG_XENO_OPT_PRIVATE_HEAPSZ for a process-private mutex.
  *
  * @see
  * <a 
href="http://www.opengroup.org/onlinepubs/000095399/functions/pthread_mutex_init.html";>
@@ -591,9 +591,9 @@ int pthread_mutexattr_destroy(pthread_mutexattr_t * attr);
  * This service stores, at the address @a type, the value of the @a type
  * attribute in the mutex attributes object @a attr.
  *
- * See pthread_mutex_lock() and pthread_mutex_unlock() documentations for a
- * description of the values of the @a type attribute and their effect on a
- * mutex.
+ * See pthread_mutex_lock() and pthread_mutex_unlock() for a
+ * description of the values of the @a type attribute and their effect
+ * on a mutex.
  *
  * @param attr an initialized mutex attributes object,
  *
@@ -618,13 +618,13 @@ int pthread_mutexattr_gettype(const pthread_mutexattr_t * 
attr, int *type);
  * This service set the @a type attribute of the mutex attributes object
  * @a attr.
  *
- * See pthread_mutex_lock() and pthread_mutex_unlock() documentations for a
- * description of the values of the @a type attribute and their effect on a
- * mutex.
+ * See pthread_mutex_lock() and pthread_mutex_unlock() for a
+ * description of the values of the @a type attribute and their effect
+ * on a mutex.
  *
  * The @a PTHREAD_MUTEX_DEFAULT default @a type is the same as @a
- * PTHREAD_MUTEX_NORMAL. Note that using a Xenomai POSIX skin recursive mutex
- * with a Xenomai POSIX skin condition variable is safe (see 
pthread_cond_wait()
+ * PTHREAD_MUTEX_NORMAL. Note that using a recursive Cobalt mutex with
+ * a Cobalt condition variable is safe (see pthread_cond_wait()
  * documentation).
  *
  * @param attr an initialized mutex attributes object,
diff --git a/lib/cobalt/sched.c b/lib/cobalt/sched.c
index 7886a8e..a1a6c7c 100644
--- a/lib/cobalt/sched.c
+++ b/lib/cobalt/sched.c
@@ -174,16 +174,15 @@ COBALT_IMPL(int, sched_get_priority_max, (int policy))
 /**
  * Set the scheduling policy and parameters of the specified process.
  *
- * This service set the scheduling policy of the Xenomai process
- * identified by @a pid to the value @a pol, and its scheduling
- * parameters (i.e. its priority) to the value pointed to by @a par.
+ * This service set the scheduling policy of the Cobalt process
+ * identified by @a pid to the value @a policy, and its scheduling
+ * parameters (i.e. its priority) to the value pointed to by @a param.
  *
  * If the current Linux thread ID is passed (see gettid(2)), this
- * service turns the current thread into a Xenomai thread. If @a pid
- * is neither the identifier of the current thread nor the identifier
- * of an existing Xenomai thread, this service falls back to the
- * regular sched_setscheduler() service, causing a transition to
- * secondary mode if the caller is a Xenomai thread.
+ * service turns the current regular POSIX thread into a Cobalt
+ * thread. If @a pid is neither the identifier of the current thread
+ * nor the identifier of an existing Cobalt thread, this service falls
+ * back to the regular sched_setscheduler() service.
  *
  * @param pid target process/thread;
  *
@@ -195,8 +194,10 @@ COBALT_IMPL(int, sched_get_priority_max, (int policy))
  * @return 0 on success;
  * @return an error number if:
  * - ESRCH, @a pid is invalid;
- * - EINVAL, @a pol or @a par->sched_priority is invalid;
- * - EFAULT, @a par is an invalid address;
+ * - EINVAL, @a policy or @a param->sched_priority is invalid;
+ * - EAGAIN, insufficient memory available from the system heap,
+ *   increase CONFIG_XENO_OPT_SYS_HEAPSZ;
+ * - EFAULT, @a param is an invalid address;
  *
  * @see
  * <a 
href="http://www.opengroup.org/onlinepubs/000095399/functions/sched_setscheduler.html";>
@@ -204,23 +205,7 @@ COBALT_IMPL(int, sched_get_priority_max, (int policy))
  *
  * @note
  *
- * When creating or shadowing a Xenomai thread for the first time,
- * libcobalt installs an internal handler for the SIGSHADOW signal. If
- * you had previously installed a handler for such signal before that
- * point, such handler will be exclusively called for any SIGSHADOW
- * occurrence Xenomai did not send.
- *
- * If, however, an application-defined handler for SIGSHADOW is
- * installed afterwards, overriding the libcobalt handler, the new
- * handler is required to call cobalt_sigshadow_handler() on
- * entry. This routine returns a non-zero value for every occurrence
- * of SIGSHADOW issued by the Cobalt core. If zero instead, the
- * application-defined handler should process the signal.
- *
- * <b>int cobalt_sigshadow_handler(int sig, siginfo_t *si, void *ctxt);</b>
- *
- * You should register your handler with sigaction(2), setting the
- * SA_SIGINFO flag.
+ * See sched_setscheduler_ex().
  */
 COBALT_IMPL(int, sched_setscheduler, (pid_t pid, int policy,
                                      const struct sched_param *param))
@@ -244,14 +229,15 @@ COBALT_IMPL(int, sched_setscheduler, (pid_t pid, int 
policy,
  * Set extended scheduling policy of a process
  *
  * This service is an extended version of the sched_setscheduler()
- * service, which supports Xenomai-specific and/or additional
+ * service, which supports Cobalt-specific and/or additional
  * scheduling policies, not available with the host Linux environment.
- * It sets the scheduling policy of the Xenomai process/thread
- * identified by @a pid to the value @a pol, and the scheduling
+ * It sets the scheduling policy of the Cobalt process/thread
+ * identified by @a pid to the value @a policy, and the scheduling
  * parameters (e.g. its priority) to the value pointed to by @a par.
  *
  * If the current Linux thread ID or zero is passed (see gettid(2)),
- * this service may turn the current thread into a Xenomai thread.
+ * this service may turn the current regular POSIX thread into a
+ * Cobalt thread.
  *
  * @param pid target process/thread. If zero, the current thread is
  * assumed.
@@ -260,7 +246,7 @@ COBALT_IMPL(int, sched_setscheduler, (pid_t pid, int policy,
  * SCHED_COBALT, SCHED_RR, SCHED_SPORADIC, SCHED_TP, SCHED_QUOTA or
  * SCHED_NORMAL;
  *
- * @param param_ex scheduling parameters address. As a special
+ * @param param_ex address of scheduling parameters. As a special
  * exception, a negative sched_priority value is interpreted as if
  * SCHED_WEAK was given in @a policy, using the absolute value of this
  * parameter as the weak priority level.
@@ -274,27 +260,13 @@ COBALT_IMPL(int, sched_setscheduler, (pid_t pid, int 
policy,
  * - ESRCH, @a pid is not found;
  * - EINVAL, @a pid is negative, @a param_ex is NULL, any of @a policy or
  *   @a param_ex->sched_priority is invalid;
+ * - EAGAIN, insufficient memory available from the system heap,
+ *   increase CONFIG_XENO_OPT_SYS_HEAPSZ;
  * - EFAULT, @a param_ex is an invalid address;
  *
  * @note
  *
- * When creating or shadowing a Xenomai thread for the first time,
- * libcobalt installs an internal handler for the SIGSHADOW signal. If
- * you had previously installed a handler for such signal before that
- * point, such handler will be exclusively called for any SIGSHADOW
- * occurrence Xenomai did not send.
- *
- * If, however, an application-defined handler for SIGSHADOW is
- * installed afterwards, overriding the libcobalt handler, the new
- * handler is required to call cobalt_sigshadow_handler() on
- * entry. This routine returns a non-zero value for every occurrence
- * of SIGSHADOW issued by the Cobalt core. If zero instead, the
- * application-defined handler should process the signal.
- *
- * <b>int cobalt_sigshadow_handler(int sig, siginfo_t *si, void *ctxt);</b>
- *
- * You should register your handler with sigaction(2), setting the
- * SA_SIGINFO flag.
+ * See sched_setscheduler().
  *
  * sched_setscheduler_ex() may switch the caller to secondary mode.
  */
@@ -331,10 +303,10 @@ int sched_setscheduler_ex(pid_t pid,
 /**
  * Get the scheduling policy of the specified process.
  *
- * This service retrieves the scheduling policy of the Xenomai process
+ * This service retrieves the scheduling policy of the Cobalt process
  * identified by @a pid.
  *
- * If @a pid does not identify an existing Xenomai thread/process, this
+ * If @a pid does not identify an existing Cobalt thread/process, this
  * service falls back to the regular sched_getscheduler() service.
  *
  * @param pid target process/thread;
@@ -376,9 +348,9 @@ COBALT_IMPL(int, sched_getscheduler, (pid_t pid))
  * Get extended scheduling policy of a process
  *
  * This service is an extended version of the sched_getscheduler()
- * service, which supports Xenomai-specific and/or additional
+ * service, which supports Cobalt-specific and/or additional
  * scheduling policies, not available with the host Linux environment.
- * It retrieves the scheduling policy of the Xenomai process/thread
+ * It retrieves the scheduling policy of the Cobalt process/thread
  * identified by @a pid, and the associated scheduling parameters
  * (e.g. the priority).
  *
@@ -476,7 +448,7 @@ int sched_get_priority_max_ex(int policy)
  * - @a sched_tp_stop disables the temporal scheduling on @a cpu.  The
  * current TP schedule is not uninstalled though, and may be
  * re-started later by a @a sched_tp_start request.
- * @caution As a consequence of this request, threads assigned to the
+ * @attention As a consequence of this request, threads assigned to the
  * un-scheduled partitions may be starved from CPU time.
  *
  * - for a @a sched_tp_install operation, config.tp.nr_windows
diff --git a/lib/cobalt/semaphore.c b/lib/cobalt/semaphore.c
index f95c26c..86a469a 100644
--- a/lib/cobalt/semaphore.c
+++ b/lib/cobalt/semaphore.c
@@ -72,8 +72,9 @@ struct cobalt_sem_state *sem_get_state(struct 
cobalt_sem_shadow *shadow)
  * @retval 0 on success,
  * @retval -1 with @a errno set if:
  * - EBUSY, the semaphore @a sm was already initialized;
- * - ENOSPC, insufficient memory exists in the system heap to initialize the
- *   semaphore, increase CONFIG_XENO_OPT_SYS_HEAPSZ;
+ * - EAGAIN, insufficient memory available to initialize the
+ *   semaphore, increase CONFIG_XENO_OPT_SHARED_HEAPSZ for a process-shared
+ *   semaphore, or CONFIG_XENO_OPT_PRIVATE_HEAPSZ for a process-private 
semaphore.
  * - EINVAL, the @a value argument exceeds @a SEM_VALUE_MAX.
  *
  * @see
@@ -427,8 +428,7 @@ COBALT_IMPL(int, sem_getvalue, (sem_t *sem, int *sval))
  * @fn int sem_open(const char *name, int oflags, mode_t mode, unsigned int 
value)
  * @brief Open a named semaphore
  *
- * This service establishes a connection between the semaphore named @a name 
and
- * the calling context (kernel-space as a whole, or user-space process).
+ * This opens the semaphore named @a name.
  *
  * If no semaphore named @a name exists and @a oflags has the @a O_CREAT bit
  * set, the semaphore is created by this function, using two more arguments:
@@ -443,9 +443,8 @@ COBALT_IMPL(int, sem_getvalue, (sem_t *sem, int *sval))
  * meaning. However, for portability, using a name which starts with a slash 
and
  * contains no other slash is recommended.
  *
- * If sem_open() is called from the same context (kernel-space as a whole, or
- * user-space process) several times with the same value of @a name, the same
- * address is returned.
+ * If sem_open() is called from the same process several times for the
+ * same @a name, the same address is returned.
  *
  * @param name the name of the semaphore to be created;
  *
@@ -459,7 +458,7 @@ COBALT_IMPL(int, sem_getvalue, (sem_t *sem, int *sval))
  * - ENOENT, the bit @a O_CREAT is not set in @a oflags and the named semaphore
  *   does not exist;
  * - ENOMEM, not enough memory to create the semaphore. A usual
- *   suspect is a shortage in the Cobalt system heap, which may be
+ *   suspect is a shortage from system heap memory, which may be
  *   fixed by increasing CONFIG_XENO_OPT_SYS_HEAPSZ;
  * - EINVAL, the @a value argument exceeds @a SEM_VALUE_MAX.
  *
diff --git a/lib/cobalt/sigshadow.c b/lib/cobalt/sigshadow.c
index b3871c3..3f4e9c5 100644
--- a/lib/cobalt/sigshadow.c
+++ b/lib/cobalt/sigshadow.c
@@ -74,7 +74,7 @@ static void sigshadow_handler(int sig, siginfo_t *si, void 
*ctxt)
        if (cobalt_sigshadow_handler(sig, si, ctxt))
                return;
 
-       /* Not a signal sent by the Xenomai nucleus */
+       /* Not a signal sent by the Cobalt core */
        if (((sa->sa_flags & SA_SIGINFO) == 0 && sa->sa_handler == NULL)
            || ((sa->sa_flags & SA_SIGINFO) && sa->sa_sigaction == NULL))
                return;
diff --git a/lib/cobalt/thread.c b/lib/cobalt/thread.c
index 8a4307c..d44fcdb 100644
--- a/lib/cobalt/thread.c
+++ b/lib/cobalt/thread.c
@@ -33,7 +33,7 @@
  * @ingroup cobalt_api
  * @defgroup cobalt_api_thread Thread management
  *
- * Cobalt/POSIX thread management services
+ * Cobalt (POSIX) thread management services
  *
  * @see
  * <a 
href="http://www.opengroup.org/onlinepubs/000095399/functions/xsh_chap02_09.html#tag_02_09";>
@@ -216,8 +216,8 @@ int pthread_create_ex(pthread_t *ptid_r,
        pthread_attr_getpersonality_ex(attr_ex, &iargs.personality);
 
        /*
-        * First start a native POSIX thread, then mate a Xenomai
-        * shadow to it.
+        * First start a regular POSIX thread, then mate a Cobalt
+        * thread to it.
         */
        iargs.start = start;
        iargs.arg = arg;
@@ -260,16 +260,11 @@ out:
  * @fn int pthread_create(pthread_t *ptid_r, const pthread_attr_t *attr, void 
*(*start)(void *), void *arg)
  * @brief Create a new thread
  *
- * This service creates a thread managed by the Xenomai nucleus in
- * dual kernel configuration.
+ * This service creates a thread managed by the Cobalt core in a dual
+ * kernel configuration.
  *
- * The new thread signal mask is inherited from the current thread, if it was
- * also created with pthread_create(), otherwise the new thread signal mask is
- * empty.
- *
- * Other attributes of the new thread depend on the @a attr
- * argument. If @a attr is NULL, default values for these attributes
- * are used.
+ * Attributes of the new thread depend on the @a attr argument. If @a
+ * attr is NULL, default values for these attributes are used.
  *
  * Returning from the @a start routine has the same effect as calling
  * pthread_exit() with the return value.
@@ -286,7 +281,7 @@ out:
  * @return 0 on success;
  * @return an error number if:
  * - EINVAL, @a attr is invalid;
- * - EAGAIN, insufficient memory exists in the system heap to create a new
+ * - EAGAIN, insufficient memory available from the system heap to create a new
  *   thread, increase CONFIG_XENO_OPT_SYS_HEAPSZ;
  * - EINVAL, thread attribute @a inheritsched is set to PTHREAD_INHERIT_SCHED
  *   and the calling thread does not belong to the Cobalt interface;
@@ -297,24 +292,23 @@ out:
  *
  * @note
  *
- * When creating or shadowing a Xenomai thread for the first time in
- * user-space, Xenomai installs a handler for the SIGSHADOW signal. If
- * you had installed a handler before that, it will be automatically
- * called by Xenomai for SIGSHADOW signals that it has not sent.
+ * When creating a Cobalt thread for the first time, libcobalt
+ * installs an internal handler for the SIGSHADOW signal. If you had
+ * previously installed a handler for such signal before that point,
+ * such handler will be exclusively called for any SIGSHADOW
+ * occurrence Xenomai did not send.
  *
- * If, however, you install a signal handler for SIGSHADOW after
- * creating or shadowing the first Xenomai thread, you have to
- * explicitly call the function cobalt_sigshadow_handler at the beginning
- * of your signal handler, using its return to know if the signal was
- * in fact an internal signal of Xenomai (in which case it returns 1),
- * or if you should handle the signal (in which case it returns
- * 0). cobalt_sigshadow_handler prototype is:
+ * If, however, an application-defined handler for SIGSHADOW is
+ * installed afterwards, overriding the libcobalt handler, the new
+ * handler is required to call cobalt_sigshadow_handler() on
+ * entry. This routine returns a non-zero value for every occurrence
+ * of SIGSHADOW issued by the Cobalt core. If zero instead, the
+ * application-defined handler should process the signal.
  *
- * <b>int cobalt_sigshadow_handler(int sig, struct siginfo *si, void 
*ctxt);</b>
+ * <b>int cobalt_sigshadow_handler(int sig, siginfo_t *si, void *ctxt);</b>
  *
- * Which means that you should register your handler with sigaction,
- * using the SA_SIGINFO flag, and pass all the arguments you received
- * to cobalt_sigshadow_handler.
+ * You should register your handler with sigaction(2), setting the
+ * SA_SIGINFO flag.
  */
 COBALT_IMPL(int, pthread_create, (pthread_t *ptid_r,
                                  const pthread_attr_t *attr,
@@ -395,11 +389,11 @@ COBALT_IMPL(int, pthread_create, (pthread_t *ptid_r,
  *   blocking call instead (see PTHREAD_WARNSW notifications).
  *
  * - PTHREAD_CONFORMING can be passed in @a setmask to switch the
- *   current user-space task to its preferred runtime mode. The only
+ *   current Cobalt thread to its preferred runtime mode. The only
  *   meaningful use of this switch is to force a real-time thread back
  *   to primary mode eagerly. Other usages have no effect.
  *
- * This service is a non-portable extension of the POSIX interface.
+ * This service is a non-portable extension of the Cobalt interface.
  *
  * @param clrmask set of bits to be cleared.
  *
@@ -417,9 +411,9 @@ COBALT_IMPL(int, pthread_create, (pthread_t *ptid_r,
  * @note Setting @a clrmask and @a setmask to zero leads to a nop,
  * only returning the previous mode if @a mode_r is a valid address.
  *
- * @caution Issuing PTHREAD_CONFORMING is most likely useless or even
+ * @attention Issuing PTHREAD_CONFORMING is most likely useless or even
  * introduces pure overhead in regular applications, since the Cobalt
- * kernel performs the necessary mode switches, only when required.
+ * core performs the necessary mode switches, only when required.
  */
 int pthread_setmode_np(int clrmask, int setmask, int *mode_r)
 {
@@ -433,7 +427,7 @@ int pthread_setmode_np(int clrmask, int setmask, int 
*mode_r)
  * This service set to @a name, the name of @a thread. This name is used for
  * displaying information in /proc/xenomai/sched.
  *
- * This service is a non-portable extension of the POSIX interface.
+ * This service is a non-portable extension of the Cobalt interface.
  *
  * @param thread target thread;
  *
@@ -452,9 +446,9 @@ COBALT_IMPL(int, pthread_setname_np, (pthread_t thread, 
const char *name))
 /**
  * Send a signal to a thread.
  *
- * This service send the signal @a sig to the Xenomai POSIX skin thread @a
- * thread (created with pthread_create()). If @a sig is zero, this service 
check
- * for existence of the thread @a thread, but no signal is sent.
+ * This service send the signal @a sig to the Cobalt thread @a thread
+ * (created with pthread_create()). If @a sig is zero, this service
+ * check for existence of the thread @a thread, but no signal is sent.
  *
  * @param thread thread identifier;
  *
@@ -485,21 +479,18 @@ COBALT_IMPL(int, pthread_kill, (pthread_t thread, int 
sig))
 /**
  * Wait for termination of a specified thread.
  *
- * If the thread @a thread is running and joinable, this service blocks the
- * calling thread until the thread @a thread terminates or detaches. In this
- * case, the calling context must be a blockable context (i.e. a Xenomai thread
- * without the scheduler locked) or the root thread (i.e. a module 
initilization
- * or cleanup routine). When @a thread terminates, the calling thread is
- * unblocked and its return value is stored at* the address @a value_ptr.
+ * If @a thread is running and joinable, this service blocks the
+ * caller until @a thread terminates or detaches.  When @a thread
+ * terminates, the caller is unblocked and its return value is stored
+ * at the address @a value_ptr.
  *
- * If, on the other hand, the thread @a thread has already finished execution,
- * its return value is stored at the address @a value_ptr and this service
- * returns immediately. In this case, this service may be called from any
- * context.
+ * On the other hand, if @a thread has already finished execution, its
+ * return value collected earlier is stored at the address @a
+ * value_ptr and this service returns immediately.
  *
- * This service is a cancelation point for POSIX skin threads: if the calling
- * thread is canceled while blocked in a call to this service, the cancelation
- * request is honored and @a thread remains joinable.
+ * This service is a cancelation point for Cobalt threads: if the
+ * calling thread is canceled while blocked in a call to this service,
+ * the cancelation request is honored and @a thread remains joinable.
  *
  * Multiple simultaneous calls to pthread_join() specifying the same running
  * target thread block all the callers until the target thread terminates.
@@ -540,40 +531,36 @@ COBALT_IMPL(int, pthread_join, (pthread_t thread, void 
**retval))
  * @ingroup cobalt_api
  * @defgroup cobalt_api_sched Scheduling management
  *
- * Cobalt/POSIX scheduling management services
+ * Cobalt scheduling management services
  * @{
  */
 
 /**
  * Set the scheduling policy and parameters of the specified thread.
  *
- * This service set the scheduling policy of the Xenomai POSIX skin thread @a
- * tid to the value @a  pol, and its scheduling parameters (i.e. its priority)
- * to the value pointed to by @a par.
+ * This service set the scheduling policy of the Cobalt thread
+ * identified by @a pid to the value @a policy, and its scheduling
+ * parameters (i.e. its priority) to the value pointed to by @a param.
  *
- * When used in user-space, passing the current thread ID as @a tid argument,
- * this service turns the current thread into a Xenomai POSIX skin thread. If 
@a
- * tid is neither the identifier of the current thread nor the identifier of a
- * Xenomai POSIX skin thread this service falls back to the regular
- * pthread_setschedparam() service, hereby causing the current thread to switch
- * to secondary mode if it is Xenomai thread.
+ * If pthread_self() is passed, this service turns the current thread
+ * into a Cobalt thread. If @a thread is not the identifier of a
+ * Cobalt thread, this service falls back to the regular
+ * pthread_setschedparam() service.
  *
- * @param thread target thread;
+ * @param thread target Cobalt thread;
  *
- * @param policy scheduling policy, one of SCHED_FIFO, SCHED_RR,
- * SCHED_SPORADIC, SCHED_TP or SCHED_OTHER;
+ * @param policy scheduling policy, one of SCHED_FIFO, SCHED_RR, or
+ * SCHED_OTHER;
  *
- * @param param scheduling parameters address.
+ * @param param address of scheduling parameters.
  *
  * @return 0 on success;
  * @return an error number if:
- * - ESRCH, @a tid is invalid;
- * - EINVAL, @a pol or @a par->sched_priority is invalid;
- * - EAGAIN, in user-space, insufficient memory exists in the system heap,
+ * - ESRCH, @a pid is invalid;
+ * - EINVAL, @a policy or @a param->sched_priority is invalid;
+ * - EAGAIN, insufficient memory available from the system heap,
  *   increase CONFIG_XENO_OPT_SYS_HEAPSZ;
- * - EFAULT, in user-space, @a par is an invalid address;
- * - EPERM, in user-space, the calling process does not have superuser
- *   permissions.
+ * - EFAULT, @a param is an invalid address;
  *
  * @see
  * <a 
href="http://www.opengroup.org/onlinepubs/000095399/functions/pthread_setschedparam.html";>
@@ -581,24 +568,7 @@ COBALT_IMPL(int, pthread_join, (pthread_t thread, void 
**retval))
  *
  * @note
  *
- * When creating or shadowing a Xenomai thread for the first time in
- * user-space, Xenomai installs a handler for the SIGSHADOW signal. If you had
- * installed a handler before that, it will be automatically called by Xenomai
- * for SIGSHADOW signals that it has not sent.
- *
- * If, however, you install a signal handler for SIGSHADOW after creating
- * or shadowing the first Xenomai thread, you have to explicitly call the
- * function xeno_sigwinch_handler at the beginning of your signal handler,
- * using its return to know if the signal was in fact an internal signal of
- * Xenomai (in which case it returns 1), or if you should handle the signal (in
- * which case it returns 0). xeno_sigwinch_handler prototype is:
- *
- * <b>int xeno_sigwinch_handler(int sig, siginfo_t *si, void *ctxt);</b>
- *
- * Which means that you should register your handler with sigaction, using the
- * SA_SIGINFO flag, and pass all the arguments you received to
- * xeno_sigwinch_handler.
- *
+ * See pthread_create(), pthread_setschedparam_ex().
  */
 COBALT_IMPL(int, pthread_setschedparam, (pthread_t thread,
                                         int policy, const struct sched_param 
*param))
@@ -619,15 +589,14 @@ COBALT_IMPL(int, pthread_setschedparam, (pthread_t thread,
  * Set extended scheduling policy of thread
  *
  * This service is an extended version of the regular
- * pthread_setschedparam() service, which supports Xenomai-specific or
- * additional scheduling policies, not available with the host Linux
- * environment.
+ * pthread_setschedparam() service, which supports Cobalt-specific
+ * scheduling policies, not available with the host Linux environment.
  *
- * This service set the scheduling policy of the Xenomai thread @a
+ * This service set the scheduling policy of the Cobalt thread @a
  * thread to the value @a policy, and its scheduling parameters
  * (e.g. its priority) to the value pointed to by @a param_ex.
  *
- * If @a thread does not match the identifier of a Xenomai thread, this
+ * If @a thread does not match the identifier of a Cobalt thread, this
  * action falls back to the regular pthread_setschedparam() service.
  *
  * @param thread target Cobalt thread;
@@ -649,10 +618,10 @@ COBALT_IMPL(int, pthread_setschedparam, (pthread_t thread,
  * @return an error number if:
  * - ESRCH, @a thread is invalid;
  * - EINVAL, @a policy or @a param_ex->sched_priority is invalid;
- * - EAGAIN, in user-space, insufficient memory exists in the system heap,
+ * - EAGAIN, insufficient memory available from the system heap,
  *   increase CONFIG_XENO_OPT_SYS_HEAPSZ;
- * - EFAULT, in user-space, @a param_ex is an invalid address;
- * - EPERM, in user-space, the calling process does not have superuser
+ * - EFAULT, @a param_ex is an invalid address;
+ * - EPERM, the calling process does not have superuser
  *   permissions.
  *
  * @see
@@ -661,24 +630,7 @@ COBALT_IMPL(int, pthread_setschedparam, (pthread_t thread,
  *
  * @note
  *
- * When creating or shadowing a Xenomai thread for the first time in
- * user-space, Xenomai installs a handler for the SIGSHADOW signal. If
- * you had installed a handler before that, it will be automatically
- * called by Xenomai for SIGSHADOW signals that it has not sent.
- *
- * If, however, you install a signal handler for SIGSHADOW after
- * creating or shadowing the first Xenomai thread, you have to
- * explicitly call the function cobalt_sigshadow_handler at the
- * beginning of your signal handler, using its return to know if the
- * signal was in fact an internal signal of Xenomai (in which case it
- * returns 1), or if you should handle the signal (in which case it
- * returns 0). cobalt_sigshadow_handler prototype is:
- *
- * <b>int cobalt_sigshadow_handler(int sig, struct siginfo *si, void 
*ctxt);</b>
- *
- * Which means that you should register your handler with sigaction,
- * using the SA_SIGINFO flag, and pass all the arguments you received
- * to cobalt_sigshadow_handler.
+ * See pthread_create(), pthread_setschedparam().
  *
  * pthread_setschedparam_ex() may switch the caller to secondary mode.
  */
@@ -714,11 +666,11 @@ int pthread_setschedparam_ex(pthread_t thread,
 /**
  * Get the scheduling policy and parameters of the specified thread.
  *
- * This service returns, at the addresses @a pol and @a par, the current
- * scheduling policy and scheduling parameters (i.e. priority) of the Xenomai
- * POSIX skin thread @a tid. If this service is called from user-space and @a
- * tid is not the identifier of a Xenomai POSIX skin thread, this service
- * fallback to Linux regular pthread_getschedparam service.
+ * This service returns, at the addresses @a policy and @a par, the
+ * current scheduling policy and scheduling parameters (i.e. priority)
+ * of the Cobalt thread @a tid. If @a thread is not the identifier of
+ * a Cobalt thread, this service fallback to the regular POSIX
+ * pthread_getschedparam() service.
  *
  * @param thread target thread;
  *
@@ -758,8 +710,8 @@ COBALT_IMPL(int, pthread_getschedparam, (pthread_t thread,
  *
  * This service is an extended version of the regular
  * pthread_getschedparam() service, which also supports
- * Xenomai-specific or additional POSIX scheduling policies, not
- * available with the host Linux environment.
+ * Cobalt-specific policies, not available with the host Linux
+ * environment.
  *
  * @param thread target thread;
  *
diff --git a/lib/cobalt/timer.c b/lib/cobalt/timer.c
index 2b1a778..8713c08 100644
--- a/lib/cobalt/timer.c
+++ b/lib/cobalt/timer.c
@@ -126,8 +126,7 @@ COBALT_IMPL(int, timer_delete, (timer_t timerid))
  * started. If the member @a it_interval is not zero, the timer is
  * periodic. The current thread must be a Cobalt thread (created with
  * pthread_create()) and will be notified via signal of timer
- * expirations. Note that these notifications will cause user-space
- * threads to switch to secondary mode.
+ * expirations.
  *
  * When starting the timer, if @a flags is TIMER_ABSTIME, the expiration value
  * is interpreted as an absolute date of the clock passed to the timer_create()


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

Reply via email to