Module: xenomai-3
Branch: stable-3.0.x
Commit: f296792854f777b330dbd420052b0620e5780cdb
URL:    
http://git.xenomai.org/?p=xenomai-3.git;a=commit;h=f296792854f777b330dbd420052b0620e5780cdb

Author: Philippe Gerum <r...@xenomai.org>
Date:   Thu Apr 21 09:04:29 2016 +0200

alchemy/doc: fix and clarify documentation about calling context

---

 lib/alchemy/alarm.c         |    4 ++--
 lib/alchemy/buffer.c        |    4 ++--
 lib/alchemy/cond.c          |    4 ++--
 lib/alchemy/event.c         |    4 ++--
 lib/alchemy/heap.c          |    4 ++--
 lib/alchemy/mutex.c         |    4 ++--
 lib/alchemy/pipe.c          |    4 ++--
 lib/alchemy/queue.c         |    4 ++--
 lib/alchemy/sem.c           |    4 ++--
 lib/alchemy/task.c          |   22 +++++++++++-----------
 lib/copperplate/init.c      |   30 ++++++++++++++++++++----------
 lib/copperplate/threadobj.c |    8 ++++----
 12 files changed, 53 insertions(+), 43 deletions(-)

diff --git a/lib/alchemy/alarm.c b/lib/alchemy/alarm.c
index d813ae2..2298114 100644
--- a/lib/alchemy/alarm.c
+++ b/lib/alchemy/alarm.c
@@ -158,7 +158,7 @@ static void alarm_handler(struct timerobj *tmobj)
  * - -EPERM is returned if this service was called from an
  * asynchronous context.
  *
- * @apitags{thread-unrestricted, switch-secondary}
+ * @apitags{mode-unrestricted, switch-secondary}
  *
  * @note Alarms are process-private objects and thus cannot be shared
  * by multiple processes, even if they belong to the same Xenomai
@@ -240,7 +240,7 @@ out:
  * - -EPERM is returned if this service was called from an
  * asynchronous context.
  *
- * @apitags{thread-unrestricted, switch-secondary}
+ * @apitags{mode-unrestricted, switch-secondary}
  */
 #ifndef DOXYGEN_CPP
 CURRENT_IMPL(int, rt_alarm_delete, (RT_ALARM *alarm))
diff --git a/lib/alchemy/buffer.c b/lib/alchemy/buffer.c
index d9d7c98..88bcb9a 100644
--- a/lib/alchemy/buffer.c
+++ b/lib/alchemy/buffer.c
@@ -205,7 +205,7 @@ fnref_register(libalchemy, buffer_finalize);
  * - -EPERM is returned if this service was called from an
  * asynchronous context.
  *
- * @apitags{thread-unrestricted, switch-secondary}
+ * @apitags{mode-unrestricted, switch-secondary}
  *
  * @note Buffers can be shared by multiple processes which belong to
  * the same Xenomai session.
@@ -303,7 +303,7 @@ fail:
  * - -EPERM is returned if this service was called from an
  * asynchronous context.
  *
- * @apitags{thread-unrestricted, switch-secondary}
+ * @apitags{mode-unrestricted, switch-secondary}
  */
 int rt_buffer_delete(RT_BUFFER *bf)
 {
diff --git a/lib/alchemy/cond.c b/lib/alchemy/cond.c
index 00c2852..e825b80 100644
--- a/lib/alchemy/cond.c
+++ b/lib/alchemy/cond.c
@@ -98,7 +98,7 @@ static struct registry_operations registry_ops;
  * - -EPERM is returned if this service was called from an
  * asynchronous context.
  *
- * @apitags{thread-unrestricted, switch-secondary}
+ * @apitags{mode-unrestricted, switch-secondary}
  *
  * @note Condition variables can be shared by multiple processes which
  * belong to the same Xenomai session.
@@ -191,7 +191,7 @@ out:
  * being used in a rt_cond_wait(), rt_cond_wait_timed() or
  * rt_cond_wait_until() by another task).
  *
- * @apitags{thread-unrestricted, switch-secondary}
+ * @apitags{mode-unrestricted, switch-secondary}
  */
 int rt_cond_delete(RT_COND *cond)
 {
diff --git a/lib/alchemy/event.c b/lib/alchemy/event.c
index dd260f5..bd42bff 100644
--- a/lib/alchemy/event.c
+++ b/lib/alchemy/event.c
@@ -160,7 +160,7 @@ fnref_register(libalchemy, event_finalize);
  * - -EPERM is returned if this service was called from an
  * asynchronous context.
  *
- * @apitags{thread-unrestricted, switch-secondary}
+ * @apitags{mode-unrestricted, switch-secondary}
  *
  * @note Event flag groups can be shared by multiple processes which
  * belong to the same Xenomai session.
@@ -243,7 +243,7 @@ out:
  * - -EPERM is returned if this service was called from an
  * asynchronous context.
  *
- * @apitags{thread-unrestricted, switch-secondary}
+ * @apitags{mode-unrestricted, switch-secondary}
  */
 int rt_event_delete(RT_EVENT *event)
 {
diff --git a/lib/alchemy/heap.c b/lib/alchemy/heap.c
index 927994b..1caf5e3 100644
--- a/lib/alchemy/heap.c
+++ b/lib/alchemy/heap.c
@@ -207,7 +207,7 @@ fnref_register(libalchemy, heap_finalize);
  * - -EPERM is returned if this service was called from an
  * asynchronous context.
  *
- * @apitags{thread-unrestricted, switch-secondary}
+ * @apitags{mode-unrestricted, switch-secondary}
  *
  * @note Heaps can be shared by multiple processes which belong to the
  * same Xenomai session.
@@ -304,7 +304,7 @@ fail_cballoc:
  * - -EPERM is returned if this service was called from an
  * asynchronous context.
  *
- * @apitags{thread-unrestricted, switch-secondary}
+ * @apitags{mode-unrestricted, switch-secondary}
  */
 int rt_heap_delete(RT_HEAP *heap)
 {
diff --git a/lib/alchemy/mutex.c b/lib/alchemy/mutex.c
index ad7b034..0924c31 100644
--- a/lib/alchemy/mutex.c
+++ b/lib/alchemy/mutex.c
@@ -98,7 +98,7 @@ static struct registry_operations registry_ops;
  * - -EPERM is returned if this service was called from an
  * asynchronous context.
  *
- * @apitags{thread-unrestricted, switch-secondary}
+ * @apitags{mode-unrestricted, switch-secondary}
  *
  * @note Mutexes can be shared by multiple processes which belong to
  * the same Xenomai session.
@@ -180,7 +180,7 @@ out:
  * being used in a rt_mutex_acquite(), rt_mutex_acquire_timed() or
  * rt_mutex_acquire_until() by another task).
  *
- * @apitags{thread-unrestricted, switch-secondary}
+ * @apitags{mode-unrestricted, switch-secondary}
  */
 int rt_mutex_delete(RT_MUTEX *mutex)
 {
diff --git a/lib/alchemy/pipe.c b/lib/alchemy/pipe.c
index dc3d8d3..9973668 100644
--- a/lib/alchemy/pipe.c
+++ b/lib/alchemy/pipe.c
@@ -127,7 +127,7 @@ DEFINE_LOOKUP_PRIVATE(pipe, RT_PIPE);
  * - -EPERM is returned if this service was called from an
  * asynchronous context.
  *
- * @apitags{thread-unrestricted, switch-secondary}
+ * @apitags{mode-unrestricted, switch-secondary}
  */
 #ifndef DOXYGEN_CPP
 CURRENT_IMPL(int, rt_pipe_create,
@@ -252,7 +252,7 @@ out:
  * - -EPERM is returned if this service was called from an
  * asynchronous context.
  *
- * @apitags{thread-unrestricted, switch-secondary}
+ * @apitags{mode-unrestricted, switch-secondary}
  */
 int rt_pipe_delete(RT_PIPE *pipe)
 {
diff --git a/lib/alchemy/queue.c b/lib/alchemy/queue.c
index 410f480..891cfd1 100644
--- a/lib/alchemy/queue.c
+++ b/lib/alchemy/queue.c
@@ -185,7 +185,7 @@ fnref_register(libalchemy, queue_finalize);
  * - -EPERM is returned if this service was called from an
  * asynchronous context.
  *
- * @apitags{thread-unrestricted, switch-secondary}
+ * @apitags{mode-unrestricted, switch-secondary}
  *
  * @note Queues can be shared by multiple processes which belong to
  * the same Xenomai session.
@@ -304,7 +304,7 @@ fail_cballoc:
  * - -EPERM is returned if this service was called from an
  * asynchronous context.
  *
- * @apitags{thread-unrestricted, switch-secondary}
+ * @apitags{mode-unrestricted, switch-secondary}
  */
 int rt_queue_delete(RT_QUEUE *queue)
 {
diff --git a/lib/alchemy/sem.c b/lib/alchemy/sem.c
index 4b967ed..cc27ce1 100644
--- a/lib/alchemy/sem.c
+++ b/lib/alchemy/sem.c
@@ -170,7 +170,7 @@ fnref_register(libalchemy, sem_finalize);
  * - -EPERM is returned if this service was called from an
  * asynchronous context.
  *
- * @apitags{thread-unrestricted, switch-secondary}
+ * @apitags{mode-unrestricted, switch-secondary}
  *
  * @note Semaphores can be shared by multiple processes which belong
  * to the same Xenomai session.
@@ -254,7 +254,7 @@ out:
  * - -EPERM is returned if this service was called from an
  * asynchronous context.
  *
- * @apitags{thread-unrestricted, switch-secondary}
+ * @apitags{mode-unrestricted, switch-secondary}
  */
 int rt_sem_delete(RT_SEM *sem)
 {
diff --git a/lib/alchemy/task.c b/lib/alchemy/task.c
index 857496b..b04b356 100644
--- a/lib/alchemy/task.c
+++ b/lib/alchemy/task.c
@@ -384,7 +384,7 @@ fail_syncinit:
  * - -EEXIST is returned if the @a name is conflicting with an already
  * registered task.
  *
- * @apitags{thread-unrestricted, switch-secondary}
+ * @apitags{mode-unrestricted, switch-secondary}
  *
  * @sideeffect
  * - When running over the Cobalt core:
@@ -469,7 +469,7 @@ out:
  * when this service is called from asynchronous context, such as a
  * timer/alarm handler.
  *
- * @apitags{thread-unrestricted, switch-secondary}
+ * @apitags{mode-unrestricted, switch-secondary}
  *
  * @note The caller must be an Alchemy task if @a task is NULL.
  */
@@ -525,7 +525,7 @@ int rt_task_delete(RT_TASK *task)
  * - -ESRCH is returned if @a task no longer exists or refers to task
  * created by a different process.
  *
- * @apitags{thread-unrestricted, switch-primary}
+ * @apitags{mode-unrestricted, switch-primary}
  *
  * @note After successful completion of this service, it is neither
  * required nor valid to additionally invoke rt_task_delete() on the
@@ -562,7 +562,7 @@ int rt_task_join(RT_TASK *task)
  * according to any restrictions that may be imposed by the "cpuset"
  * mechanism described in cpuset(7).
  *
- * @apitags{thread-unrestricted, switch-secondary}
+ * @apitags{mode-unrestricted, switch-secondary}
  *
  * @note The caller must be an Alchemy task if @a task is NULL.
  */
@@ -610,7 +610,7 @@ out:
  *
  * - -EINVAL is returned if @a task is not a valid task descriptor.
  *
- * @apitags{thread-unrestricted, switch-primary}
+ * @apitags{mode-unrestricted, switch-primary}
  *
  * @note Starting an already started task leads to a nop, returning a
  * success status.
@@ -800,7 +800,7 @@ undo:
  * - -ETIMEDOUT is returned if @a idate is different from TM_INFINITE
  * and represents a date in the past.
  *
- * @apitags{thread-unrestricted, switch-primary}
+ * @apitags{mode-unrestricted, switch-primary}
  *
  * @note The caller must be an Alchemy task if @a task is NULL.
  *
@@ -1036,7 +1036,7 @@ int rt_task_sleep(RTIME delay)
  *
  * @return See rt_task_create().
  *
- * @apitags{thread-unrestricted, switch-secondary}
+ * @apitags{mode-unrestricted, switch-secondary}
  *
  * @sideeffect see rt_task_create().
  */
@@ -1114,7 +1114,7 @@ int rt_task_same(RT_TASK *task1, RT_TASK *task2)
  * - -EPERM is returned if @a task is NULL and this service was called
  * from an invalid context.
  *
- * @apitags{thread-unrestricted, switch-primary}
+ * @apitags{mode-unrestricted, switch-primary}
  *
  * @note The caller must be an Alchemy task if @a task is NULL.
  *
@@ -1240,7 +1240,7 @@ RT_TASK *rt_task_self(void)
  * - -EPERM is returned if @a task is NULL and this service was called
  * from an invalid context.
  *
- * @apitags{thread-unrestricted, switch-primary}
+ * @apitags{mode-unrestricted, switch-primary}
  *
  * @note The caller must be an Alchemy task if @a task is NULL.
  *
@@ -1373,7 +1373,7 @@ out:
  * - -EPERM is returned if @a task is NULL and this service was called
  * from an invalid context.
  *
- * @apitags{thread-unrestricted, switch-primary}
+ * @apitags{mode-unrestricted, switch-primary}
  *
  * @note The caller must be an Alchemy task if @a task is NULL.
  *
@@ -1530,7 +1530,7 @@ out:
  * - -EPERM is returned if @a task is NULL and this service was called
  * from an invalid context.
  *
- * @apitags{thread-unrestricted, switch-primary}
+ * @apitags{mode-unrestricted, switch-primary}
  *
  * @note The caller must be an Alchemy task if @a task is NULL.
  */
diff --git a/lib/copperplate/init.c b/lib/copperplate/init.c
index 3ce4584..4ea5e1a 100644
--- a/lib/copperplate/init.c
+++ b/lib/copperplate/init.c
@@ -304,23 +304,26 @@ copperplate_setup_call(copperplate_interface);
  *
  * All services from the Cobalt/POSIX library, or which belong to APIs
  * based on the Copperplate library may be restricted to particular
- * calling contexts, or entail specific side-effects. Therefore, the
- * information below applies to all application-oriented APIs
- * available with Xenomai, such as the Cobalt/POSIX library, the
- * Alchemy API, and to all RTOS emulators as well. To describe this
- * information, each service documented by this section bears a set of
- * tags when applicable.
+ * calling contexts, or entail specific side-effects.
+ *
+ * In dual kernel mode, the Cobalt API underlies all other
+ * application-oriented APIs, providing POSIX real-time services over
+ * the Cobalt real-time core. Therefore, the information below applies
+ * to all application-oriented APIs available with Xenomai, such as
+ * the Cobalt/POSIX library, the Alchemy API, and to all RTOS
+ * emulators as well. To describe this information, each service
+ * documented by this section bears a set of tags when applicable.
  *
  * The table below matches the tags used throughout the documentation
  * with the description of their meaning for the caller.
  *
  * @attention By Xenomai thread, we mean any thread created by a
  * Xenomai API service, including real-time Cobalt/POSIX threads in
- * dual kernel mode. By regular POSIX thread, we mean any thread
+ * dual kernel mode. By regular/plain POSIX thread, we mean any thread
  * directly created by the standard @a glibc-based POSIX service over
- * Mercury (i.e. NPTL/linuxthreads pthread_create()), excluding such
- * threads which have been promoted to the real-time domain afterwards
- * (aka "shadowed") over Cobalt.
+ * Mercury or Cobalt (i.e. NPTL/linuxthreads __STD(pthread_create())),
+ * excluding such threads which have been promoted to the real-time
+ * domain afterwards (aka "shadowed") over Cobalt.
  *
  * @par
  * <b>Context tags</b>
@@ -344,6 +347,13 @@ copperplate_setup_call(copperplate_interface);
  * services from asynchronous regular signal handlers is fundamentally
  * unsafe.
  *
+ * @note Over Cobalt, the main thread is a particular case, which
+ * starts as a regular POSIX thread, then is automatically switched to
+ * a Cobalt thread as part of the initialization process, before the
+ * main() routine is invoked, unless automatic bootstrap was disabled
+ * (see
+ * 
http://xenomai.org/2015/05/application-setup-and-init/#Application_entry_CC).
+ *
  * @par
  * <b>Possible side-effects when running the application over the
  * Cobalt core (i.e. dual kernel configuration)</b>
diff --git a/lib/copperplate/threadobj.c b/lib/copperplate/threadobj.c
index e0b2c9f..831446a 100644
--- a/lib/copperplate/threadobj.c
+++ b/lib/copperplate/threadobj.c
@@ -1754,13 +1754,13 @@ static inline int main_overlay(void)
 
        /*
         * Make the main() context a basic yet complete thread object,
-        * so that it may use any services which require the caller to
+        * so that it may use any service which requires the caller to
         * have a Copperplate TCB (e.g. all blocking services). We
         * allocate a wait union which should be sufficient for
         * calling any blocking service from any high-level API from
-        * an unshadowed main thread. APIs might have other reasons
-        * not to allow such call though, in which case they should
-        * check explicitly for those conditions.
+        * an unshadowed main thread. APIs might have reasons not to
+        * allow such call though, in which case they should check
+        * explicitly for those conditions.
         */
        tcb = __threadobj_alloc(sizeof(*tcb),
                                sizeof(union main_wait_union),


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

Reply via email to