Module: xenomai-3
Branch: master
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
