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 <[email protected]> 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 [email protected] https://xenomai.org/mailman/listinfo/xenomai-git
