Module: xenomai-3 Branch: next Commit: 88e0e30cb1c1a5b2ab07724fb8964d3d6fc63af2 URL: http://git.xenomai.org/?p=xenomai-3.git;a=commit;h=88e0e30cb1c1a5b2ab07724fb8964d3d6fc63af2
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