Module: xenomai-3 Branch: next Commit: b0cf167b7e9b181967eb5c618296729c03990db5 URL: http://git.xenomai.org/?p=xenomai-3.git;a=commit;h=b0cf167b7e9b181967eb5c618296729c03990db5
Author: Philippe Gerum <r...@xenomai.org> Date: Thu Oct 1 21:27:40 2015 +0200 lib/cobalt: add API context tags --- lib/cobalt/clock.c | 11 +++++++++++ lib/cobalt/cond.c | 15 ++++++++++++++- lib/cobalt/mq.c | 11 +++++++++++ lib/cobalt/mutex.c | 14 ++++++++++++++ lib/cobalt/sched.c | 17 ++++++++++++++++- lib/cobalt/semaphore.c | 19 +++++++++++++++++++ lib/cobalt/thread.c | 15 ++++++++++++++- lib/cobalt/timer.c | 8 ++++++++ lib/copperplate/init.c | 44 +++++++++++++++++++++++++++----------------- 9 files changed, 134 insertions(+), 20 deletions(-) diff --git a/lib/cobalt/clock.c b/lib/cobalt/clock.c index 3fe6658..0450019 100644 --- a/lib/cobalt/clock.c +++ b/lib/cobalt/clock.c @@ -95,6 +95,7 @@ * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/clock_getres.html";> * Specification.</a> * + * @apitags{unrestricted} */ COBALT_IMPL(int, clock_getres, (clockid_t clock_id, struct timespec *tp)) { @@ -175,6 +176,7 @@ static int __do_clock_host_realtime(struct timespec *ts) * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/clock_gettime.html";> * Specification.</a> * + * @apitags{unrestricted} */ COBALT_IMPL(int, clock_gettime, (clockid_t clock_id, struct timespec *tp)) { @@ -229,6 +231,7 @@ COBALT_IMPL(int, clock_gettime, (clockid_t clock_id, struct timespec *tp)) * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/clock_settime.html";> * Specification.</a> * + * @apitags{unrestricted} */ COBALT_IMPL(int, clock_settime, (clockid_t clock_id, const struct timespec *tp)) { @@ -281,6 +284,7 @@ COBALT_IMPL(int, clock_settime, (clockid_t clock_id, const struct timespec *tp)) * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/clock_nanosleep.html";> * Specification.</a> * + * @apitags{xthread-only, switch-primary} */ COBALT_IMPL(int, clock_nanosleep, (clockid_t clock_id, int flags, @@ -326,6 +330,7 @@ COBALT_IMPL(int, clock_nanosleep, (clockid_t clock_id, * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/nanosleep.html";> * Specification.</a> * + * @apitags{xthread-only, switch-primary} */ COBALT_IMPL(int, nanosleep, (const struct timespec *rqtp, struct timespec *rmtp)) { @@ -340,6 +345,8 @@ COBALT_IMPL(int, nanosleep, (const struct timespec *rqtp, struct timespec *rmtp) return 0; } +/* @apitags{thread-unrestricted, switch-primary} */ + COBALT_IMPL(unsigned int, sleep, (unsigned int seconds)) { struct timespec rqt, rem; @@ -357,6 +364,8 @@ COBALT_IMPL(unsigned int, sleep, (unsigned int seconds)) return 0; } +/* @apitags{unrestricted} */ + COBALT_IMPL(int, gettimeofday, (struct timeval *tv, struct timezone *tz)) { struct timespec ts; @@ -368,6 +377,8 @@ COBALT_IMPL(int, gettimeofday, (struct timeval *tv, struct timezone *tz)) return ret; } +/* @apitags{unrestricted} */ + COBALT_IMPL(time_t, time, (time_t *t)) { struct timespec ts; diff --git a/lib/cobalt/cond.c b/lib/cobalt/cond.c index bb9e84c..19ef372 100644 --- a/lib/cobalt/cond.c +++ b/lib/cobalt/cond.c @@ -107,6 +107,8 @@ void cobalt_default_condattr_init(void) * @see * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/pthread_cond_init.html";> * Specification.</a> + * + * @apitags{thread-unrestricted} */ COBALT_IMPL(int, pthread_cond_init, (pthread_cond_t *cond, const pthread_condattr_t * attr)) @@ -161,6 +163,7 @@ COBALT_IMPL(int, pthread_cond_init, (pthread_cond_t *cond, * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/pthread_cond_destroy.html";> * Specification.</a> * + * @apitags{thread-unrestricted} */ COBALT_IMPL(int, pthread_cond_destroy, (pthread_cond_t *cond)) { @@ -245,6 +248,7 @@ static int __attribute__((cold)) cobalt_cond_autoinit(pthread_cond_t *cond) * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/pthread_cond_wait.html";> * Specification.</a> * + * @apitags{xthread-only, switch-primary} */ COBALT_IMPL(int, pthread_cond_wait, (pthread_cond_t *cond, pthread_mutex_t *mutex)) { @@ -338,6 +342,7 @@ COBALT_IMPL(int, pthread_cond_wait, (pthread_cond_t *cond, pthread_mutex_t *mute * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/pthread_cond_timedwait.html";> * Specification.</a> * + * @apitags{xthread-only, switch-primary} */ COBALT_IMPL(int, pthread_cond_timedwait, (pthread_cond_t *cond, pthread_mutex_t *mutex, @@ -418,7 +423,8 @@ COBALT_IMPL(int, pthread_cond_timedwait, (pthread_cond_t *cond, * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/pthread_cond_signal.html.";> * Specification.</a> * - */ + * @apitags{xthread-only} +*/ COBALT_IMPL(int, pthread_cond_signal, (pthread_cond_t *cond)) { struct cobalt_cond_shadow *_cnd = &((union cobalt_cond_union *)cond)->shadow_cond; @@ -478,6 +484,7 @@ COBALT_IMPL(int, pthread_cond_signal, (pthread_cond_t *cond)) * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/pthread_cond_broadcast.html";> * Specification.</a> * + * @apitags{xthread-only} */ COBALT_IMPL(int, pthread_cond_broadcast, (pthread_cond_t *cond)) { @@ -540,6 +547,7 @@ COBALT_IMPL(int, pthread_cond_broadcast, (pthread_cond_t *cond)) * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/pthread_condattr_init.html";> * Specification.</a> * + * @apitags{thread-unrestricted} */ int pthread_condattr_init(pthread_condattr_t * attr); @@ -560,6 +568,7 @@ int pthread_condattr_init(pthread_condattr_t * attr); * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/pthread_condattr_destroy.html";> * Specification.</a> * + * @apitags{thread-unrestricted} */ int pthread_condattr_destroy(pthread_condattr_t * attr); @@ -587,6 +596,7 @@ int pthread_condattr_destroy(pthread_condattr_t * attr); * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/pthread_condattr_getclock.html";> * Specification.</a> * + * @apitags{thread-unrestricted} */ int pthread_condattr_getclock(const pthread_condattr_t * attr, clockid_t * clk_id); @@ -614,6 +624,7 @@ int pthread_condattr_getclock(const pthread_condattr_t * attr, * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/pthread_condattr_setclock.html";> * Specification.</a> * + * @apitags{thread-unrestricted} */ int pthread_condattr_setclock(pthread_condattr_t * attr, clockid_t clk_id); @@ -642,6 +653,7 @@ int pthread_condattr_setclock(pthread_condattr_t * attr, clockid_t clk_id); * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/pthread_condattr_getpshared.html";> * Specification.</a> * + * @apitags{thread-unrestricted} */ int pthread_condattr_getpshared(const pthread_condattr_t *attr, int *pshared); @@ -670,6 +682,7 @@ int pthread_condattr_getpshared(const pthread_condattr_t *attr, int *pshared); * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/pthread_condattr_setpshared.html";> * Specification.</a> * + * @apitags{thread-unrestricted} */ int pthread_condattr_setpshared(pthread_condattr_t *attr, int pshared); diff --git a/lib/cobalt/mq.c b/lib/cobalt/mq.c index 177c903..a361688 100644 --- a/lib/cobalt/mq.c +++ b/lib/cobalt/mq.c @@ -97,6 +97,8 @@ * @see * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/mq_open.html";> * Specification.</a> + * + * @apitags{thread-unrestricted, switch-secondary} */ COBALT_IMPL(mqd_t, mq_open, (const char *name, int oflags, ...)) { @@ -139,6 +141,7 @@ COBALT_IMPL(mqd_t, mq_open, (const char *name, int oflags, ...)) * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/mq_close.html";> * Specification.</a> * + * @apitags{thread-unrestricted, switch-secondary} */ COBALT_IMPL(int, mq_close, (mqd_t mqd)) { @@ -174,6 +177,7 @@ COBALT_IMPL(int, mq_close, (mqd_t mqd)) * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/mq_unlink.html";> * Specification.</a> * + * @apitags{thread-unrestricted, switch-secondary} */ COBALT_IMPL(int, mq_unlink, (const char *name)) { @@ -212,6 +216,7 @@ COBALT_IMPL(int, mq_unlink, (const char *name)) * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/mq_getattr.html";> * Specification.</a> * + * @apitags{thread-unrestricted} */ COBALT_IMPL(int, mq_getattr, (mqd_t mqd, struct mq_attr *attr)) { @@ -252,6 +257,7 @@ COBALT_IMPL(int, mq_getattr, (mqd_t mqd, struct mq_attr *attr)) * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/mq_setattr.html";> * Specification.</a> * + * @apitags{thread-unrestricted} */ COBALT_IMPL(int, mq_setattr, (mqd_t mqd, const struct mq_attr *__restrict__ attr, @@ -317,6 +323,7 @@ COBALT_IMPL(int, mq_setattr, (mqd_t mqd, * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/mq_send.html";> * Specification.</a> * + * @apitags{xthread-only, switch-primary} */ COBALT_IMPL(int, mq_send, (mqd_t q, const char *buffer, size_t len, unsigned prio)) { @@ -370,6 +377,7 @@ COBALT_IMPL(int, mq_send, (mqd_t q, const char *buffer, size_t len, unsigned pri * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/mq_timedsend.html";> * Specification.</a> * + * @apitags{xthread-only, switch-primary} */ COBALT_IMPL(int, mq_timedsend, (mqd_t q, const char *buffer, @@ -433,6 +441,7 @@ COBALT_IMPL(int, mq_timedsend, (mqd_t q, * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/mq_receive.html";> * Specification.</a> * + * @apitags{xthread-only, switch-primary} */ COBALT_IMPL(ssize_t, mq_receive, (mqd_t q, char *buffer, size_t len, unsigned *prio)) { @@ -490,6 +499,7 @@ COBALT_IMPL(ssize_t, mq_receive, (mqd_t q, char *buffer, size_t len, unsigned *p * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/mq_timedreceive.html";> * Specification.</a> * + * @apitags{xthread-only, switch-primary} */ COBALT_IMPL(ssize_t, mq_timedreceive, (mqd_t q, char *__restrict__ buffer, @@ -550,6 +560,7 @@ COBALT_IMPL(ssize_t, mq_timedreceive, (mqd_t q, * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/mq_notify.html";> * Specification.</a> * + * @apitags{xthread-only, switch-primary} */ COBALT_IMPL(int, mq_notify, (mqd_t mqd, const struct sigevent *evp)) { diff --git a/lib/cobalt/mutex.c b/lib/cobalt/mutex.c index b2d7b65..e4024e3 100644 --- a/lib/cobalt/mutex.c +++ b/lib/cobalt/mutex.c @@ -87,6 +87,7 @@ void cobalt_default_mutexattr_init(void) * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/pthread_mutex_init.html";> * Specification.</a> * + * @apitags{thread-unrestricted} */ COBALT_IMPL(int, pthread_mutex_init, (pthread_mutex_t *mutex, const pthread_mutexattr_t *attr)) @@ -156,6 +157,7 @@ COBALT_IMPL(int, pthread_mutex_init, (pthread_mutex_t *mutex, * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/pthread_mutex_destroy.html";> * Specification.</a> * + * @apitags{thread-unrestricted} */ COBALT_IMPL(int, pthread_mutex_destroy, (pthread_mutex_t *mutex)) { @@ -229,6 +231,7 @@ static int __attribute__((cold)) cobalt_mutex_autoinit(pthread_mutex_t *mutex) * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/pthread_mutex_lock.html";> * Specification.</a> * + * @apitags{xthread-only, switch-primary} */ COBALT_IMPL(int, pthread_mutex_lock, (pthread_mutex_t *mutex)) { @@ -323,6 +326,7 @@ COBALT_IMPL(int, pthread_mutex_lock, (pthread_mutex_t *mutex)) * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/pthread_mutex_timedlock.html";> * Specification.</a> * + * @apitags{xthread-only, switch-primary} */ COBALT_IMPL(int, pthread_mutex_timedlock, (pthread_mutex_t *mutex, const struct timespec *to)) @@ -408,6 +412,7 @@ COBALT_IMPL(int, pthread_mutex_timedlock, (pthread_mutex_t *mutex, * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/pthread_mutex_trylock.html";> * Specification.</a> * + * @apitags{xthread-only, switch-primary} */ COBALT_IMPL(int, pthread_mutex_trylock, (pthread_mutex_t *mutex)) { @@ -491,6 +496,7 @@ do_syscall: * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/pthread_mutex_unlock.html";> * Specification.</a> * + * @apitags{xthread-only, switch-primary} */ COBALT_IMPL(int, pthread_mutex_unlock, (pthread_mutex_t *mutex)) { @@ -562,6 +568,7 @@ do_syscall: * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/pthread_mutexattr_init.html";> * Specification.</a> * + * @apitags{thread-unrestricted} */ int pthread_mutexattr_init(pthread_mutexattr_t * attr); @@ -582,6 +589,7 @@ int pthread_mutexattr_init(pthread_mutexattr_t * attr); * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/pthread_mutexattr_destroy.html";> * Specification.</a> * + * @apitags{thread-unrestricted} */ int pthread_mutexattr_destroy(pthread_mutexattr_t * attr); @@ -609,6 +617,7 @@ int pthread_mutexattr_destroy(pthread_mutexattr_t * attr); * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/pthread_mutexattr_gettype.html";> * Specification.</a> * + * @apitags{thread-unrestricted} */ int pthread_mutexattr_gettype(const pthread_mutexattr_t * attr, int *type); @@ -640,6 +649,7 @@ int pthread_mutexattr_gettype(const pthread_mutexattr_t * attr, int *type); * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/pthread_mutexattr_settype.html";> * Specification.</a> * + * @apitags{thread-unrestricted} */ int pthread_mutexattr_settype(pthread_mutexattr_t * attr, int type); @@ -667,6 +677,7 @@ int pthread_mutexattr_settype(pthread_mutexattr_t * attr, int type); * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/pthread_mutexattr_getprotocol.html";> * Specification.</a> * + * @apitags{thread-unrestricted} */ int pthread_mutexattr_getprotocol(const pthread_mutexattr_t * attr, int *proto); @@ -696,6 +707,7 @@ int pthread_mutexattr_getprotocol(const pthread_mutexattr_t * attr, int *proto); * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/pthread_mutexattr_setprotocol.html";> * Specification.</a> * + * @apitags{thread-unrestricted} */ int pthread_mutexattr_setprotocol(pthread_mutexattr_t * attr, int proto); @@ -723,6 +735,7 @@ int pthread_mutexattr_setprotocol(pthread_mutexattr_t * attr, int proto); * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/pthread_mutexattr_getpshared.html";> * Specification.</a> * + * @apitags{thread-unrestricted} */ int pthread_mutexattr_getpshared(const pthread_mutexattr_t *attr, int *pshared); @@ -751,6 +764,7 @@ int pthread_mutexattr_getpshared(const pthread_mutexattr_t *attr, int *pshared); * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/pthread_mutexattr_setpshared.html";> * Specification.</a> * + * @apitags{thread-unrestricted} */ int pthread_mutexattr_setpshared(pthread_mutexattr_t *attr, int pshared); diff --git a/lib/cobalt/sched.c b/lib/cobalt/sched.c index a1a6c7c..7376110 100644 --- a/lib/cobalt/sched.c +++ b/lib/cobalt/sched.c @@ -53,6 +53,7 @@ * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/sched_yield.html";> * Specification.</a> * + * @apitags{thread-unrestricted, switch-primary} */ COBALT_IMPL(int, sched_yield, (void)) { @@ -79,6 +80,7 @@ COBALT_IMPL(int, sched_yield, (void)) * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/sched_get_priority_min.html";> * Specification.</a> * + * @apitags{thread-unrestricted} */ COBALT_IMPL(int, sched_get_priority_min, (int policy)) { @@ -117,6 +119,7 @@ COBALT_IMPL(int, sched_get_priority_min, (int policy)) * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/sched_get_priority_min.html";> * Specification.</a> * + * @apitags{thread-unrestricted} */ int sched_get_priority_min_ex(int policy) { @@ -149,6 +152,7 @@ int sched_get_priority_min_ex(int policy) * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/sched_get_priority_max.html";> * Specification.</a> * + * @apitags{thread-unrestricted} */ COBALT_IMPL(int, sched_get_priority_max, (int policy)) { @@ -206,6 +210,8 @@ COBALT_IMPL(int, sched_get_priority_max, (int policy)) * @note * * See sched_setscheduler_ex(). + * + * @apitags{thread-unrestricted, switch-secondary, switch-primary} */ COBALT_IMPL(int, sched_setscheduler, (pid_t pid, int policy, const struct sched_param *param)) @@ -268,7 +274,7 @@ COBALT_IMPL(int, sched_setscheduler, (pid_t pid, int policy, * * See sched_setscheduler(). * - * sched_setscheduler_ex() may switch the caller to secondary mode. + * @apitags{thread-unrestricted, switch-secondary, switch-primary} */ int sched_setscheduler_ex(pid_t pid, int policy, const struct sched_param_ex *param_ex) @@ -320,6 +326,8 @@ int sched_setscheduler_ex(pid_t pid, * @see * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/sched_getscheduler.html";> * Specification.</a> + * + * @apitags{thread-unrestricted} */ COBALT_IMPL(int, sched_getscheduler, (pid_t pid)) { @@ -368,6 +376,8 @@ COBALT_IMPL(int, sched_getscheduler, (pid_t pid)) * - ESRCH, @a pid is not a Cobalt thread; * - EINVAL, @a pid is negative or @a param_ex is NULL; * - EFAULT, @a param_ex is an invalid address; + * + * @apitags{thread-unrestricted} */ int sched_getscheduler_ex(pid_t pid, int *policy_r, struct sched_param_ex *param_ex) @@ -395,6 +405,7 @@ int sched_getscheduler_ex(pid_t pid, int *policy_r, * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/sched_get_priority_max.html";> * Specification.</a> * + * @apitags{thread-unrestricted} */ int sched_get_priority_max_ex(int policy) { @@ -524,6 +535,8 @@ int sched_get_priority_max_ex(int policy) * * - ESRCH, with @a policy equal to SCHED_QUOTA, if the group * identifier required to perform the operation is not valid. + * + * @apitags{thread-unrestricted, switch-primary} */ int sched_setconfig_np(int cpu, int policy, const union sched_config *config, size_t len) @@ -579,6 +592,8 @@ int sched_setconfig_np(int cpu, int policy, * - ENOMEM, lack of memory to perform the operation. * * - ENOSPC, @a len is too short. + * + * @apitags{thread-unrestricted, switch-primary} */ ssize_t sched_getconfig_np(int cpu, int policy, union sched_config *config, size_t *len_r) diff --git a/lib/cobalt/semaphore.c b/lib/cobalt/semaphore.c index 86a469a..5a69968 100644 --- a/lib/cobalt/semaphore.c +++ b/lib/cobalt/semaphore.c @@ -81,6 +81,7 @@ struct cobalt_sem_state *sem_get_state(struct cobalt_sem_shadow *shadow) * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/sem_init.html";> * Specification.</a> * + * @apitags{thread-unrestricted} */ COBALT_IMPL(int, sem_init, (sem_t *sem, int pshared, unsigned int value)) { @@ -131,6 +132,8 @@ COBALT_IMPL(int, sem_init, (sem_t *sem, int pshared, unsigned int value)) * @see * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/sem_destroy.html";> * Specification.</a> + * + * @apitags{thread-unrestricted} */ COBALT_IMPL(int, sem_destroy, (sem_t *sem)) { @@ -175,6 +178,8 @@ COBALT_IMPL(int, sem_destroy, (sem_t *sem)) * @see * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/sem_post.html";> * Specification.</a> + * + * @apitags{unrestricted} */ COBALT_IMPL(int, sem_post, (sem_t *sem)) { @@ -235,6 +240,8 @@ COBALT_IMPL(int, sem_post, (sem_t *sem)) * * @see * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/sem_trywait.html";> * Specification.</a> + * + * @apitags{xthread-only} */ COBALT_IMPL(int, sem_trywait, (sem_t *sem)) { @@ -296,6 +303,8 @@ eagain: * @see * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/sem_wait.html";> * Specification.</a> + * + * @apitags{xthread-only, switch-primary} */ COBALT_IMPL(int, sem_wait, (sem_t *sem)) { @@ -349,6 +358,8 @@ COBALT_IMPL(int, sem_wait, (sem_t *sem)) * @see * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/sem_timedwait.html";> * Specification.</a> + * + * @apitags{xthread-only, switch-primary} */ COBALT_IMPL(int, sem_timedwait, (sem_t *sem, const struct timespec *abs_timeout)) { @@ -400,6 +411,8 @@ COBALT_IMPL(int, sem_timedwait, (sem_t *sem, const struct timespec *abs_timeout) * @see * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/sem_getvalue.html";> * Specification.</a> + * + * @apitags{unrestricted} */ COBALT_IMPL(int, sem_getvalue, (sem_t *sem, int *sval)) { @@ -465,6 +478,8 @@ COBALT_IMPL(int, sem_getvalue, (sem_t *sem, int *sval)) * @see * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/sem_open.html";> * Specification.</a> + * + * @apitags{thread-unrestricted, switch-secondary} */ COBALT_IMPL(sem_t *, sem_open, (const char *name, int oflags, ...)) { @@ -526,6 +541,8 @@ error: * @see * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/sem_close.html";> * Specification.</a> + * + * @apitags{thread-unrestricted, switch-secondary} */ COBALT_IMPL(int, sem_close, (sem_t *sem)) { @@ -571,6 +588,8 @@ COBALT_IMPL(int, sem_close, (sem_t *sem)) * @see * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/sem_unlink.html";> * Specification.</a> + * + * @apitags{thread-unrestricted, switch-secondary} */ COBALT_IMPL(int, sem_unlink, (const char *name)) { diff --git a/lib/cobalt/thread.c b/lib/cobalt/thread.c index d44fcdb..abb0b41 100644 --- a/lib/cobalt/thread.c +++ b/lib/cobalt/thread.c @@ -309,6 +309,8 @@ out: * * You should register your handler with sigaction(2), setting the * SA_SIGINFO flag. + * + * @apitags{thread-unrestricted, switch-secondary} */ COBALT_IMPL(int, pthread_create, (pthread_t *ptid_r, const pthread_attr_t *attr, @@ -414,6 +416,8 @@ COBALT_IMPL(int, pthread_create, (pthread_t *ptid_r, * @attention Issuing PTHREAD_CONFORMING is most likely useless or even * introduces pure overhead in regular applications, since the Cobalt * core performs the necessary mode switches, only when required. + * + * @apitags{xthread-only, switch-primary} */ int pthread_setmode_np(int clrmask, int setmask, int *mode_r) { @@ -437,6 +441,7 @@ int pthread_setmode_np(int clrmask, int setmask, int *mode_r) * @return an error number if: * - ESRCH, @a thread is invalid. * + * @apitags{xthread-only} */ COBALT_IMPL(int, pthread_setname_np, (pthread_t thread, const char *name)) { @@ -464,6 +469,7 @@ COBALT_IMPL(int, pthread_setname_np, (pthread_t thread, const char *name)) * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/pthread_kill.html";> * Specification.</a> * + * @apitags{thread-unrestricted, switch-primary} */ COBALT_IMPL(int, pthread_kill, (pthread_t thread, int sig)) { @@ -511,6 +517,7 @@ COBALT_IMPL(int, pthread_kill, (pthread_t thread, int sig)) * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/pthread_join.html";> * Specification.</a> * + * @apitags{xthread-only, switch-secondary, switch-primary} */ COBALT_IMPL(int, pthread_join, (pthread_t thread, void **retval)) { @@ -569,6 +576,8 @@ COBALT_IMPL(int, pthread_join, (pthread_t thread, void **retval)) * @note * * See pthread_create(), pthread_setschedparam_ex(). + * + * @apitags{thread-unrestricted, switch-secondary, switch-primary} */ COBALT_IMPL(int, pthread_setschedparam, (pthread_t thread, int policy, const struct sched_param *param)) @@ -632,7 +641,7 @@ COBALT_IMPL(int, pthread_setschedparam, (pthread_t thread, * * See pthread_create(), pthread_setschedparam(). * - * pthread_setschedparam_ex() may switch the caller to secondary mode. + * @apitags{thread-unrestricted, switch-secondary, switch-primary} */ int pthread_setschedparam_ex(pthread_t thread, int policy, const struct sched_param_ex *param_ex) @@ -688,6 +697,7 @@ int pthread_setschedparam_ex(pthread_t thread, * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/pthread_getschedparam.html";> * Specification.</a> * + * @apitags{thread-unrestricted} */ COBALT_IMPL(int, pthread_getschedparam, (pthread_t thread, int *__restrict__ policy, @@ -728,6 +738,8 @@ COBALT_IMPL(int, pthread_getschedparam, (pthread_t thread, * @see * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/pthread_getschedparam.html";> * Specification.</a> + * + * @apitags{thread-unrestricted} */ int pthread_getschedparam_ex(pthread_t thread, int *__restrict__ policy_r, @@ -758,6 +770,7 @@ int pthread_getschedparam_ex(pthread_t thread, * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/sched_yield.html";> * Specification.</a> * + * @apitags{thread-unrestricted, switch-primary} */ COBALT_IMPL(int, pthread_yield, (void)) { diff --git a/lib/cobalt/timer.c b/lib/cobalt/timer.c index 8713c08..e3a1e88 100644 --- a/lib/cobalt/timer.c +++ b/lib/cobalt/timer.c @@ -66,6 +66,8 @@ * @see * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/timer_create.html";> * Specification.</a> + * + * @apitags{thread-unrestricted} */ COBALT_IMPL(int, timer_create, (clockid_t clockid, const struct sigevent *__restrict__ evp, @@ -98,6 +100,7 @@ COBALT_IMPL(int, timer_create, (clockid_t clockid, * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/timer_delete.html";> * Specification.</a> * + * @apitags{thread-unrestricted} */ COBALT_IMPL(int, timer_delete, (timer_t timerid)) { @@ -153,6 +156,8 @@ COBALT_IMPL(int, timer_delete, (timer_t timerid)) * @see * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/timer_settime.html";> * Specification.</a> + * + * @apitags{xcontext, switch-primary} */ COBALT_IMPL(int, timer_settime, (timer_t timerid, int flags, @@ -197,6 +202,8 @@ COBALT_IMPL(int, timer_settime, (timer_t timerid, * @see * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/timer_gettime.html";> * Specification.</a> + * + * @apitags{unrestricted} */ COBALT_IMPL(int, timer_gettime, (timer_t timerid, struct itimerspec *value)) { @@ -230,6 +237,7 @@ COBALT_IMPL(int, timer_gettime, (timer_t timerid, struct itimerspec *value)) * <a href="http://www.opengroup.org/onlinepubs/000095399/functions/timer_getoverrun.html";> * Specification.</a> * + * @apitags{unrestricted} */ COBALT_IMPL(int, timer_getoverrun, (timer_t timerid)) { diff --git a/lib/copperplate/init.c b/lib/copperplate/init.c index f26b2db..f12bffc 100644 --- a/lib/copperplate/init.c +++ b/lib/copperplate/init.c @@ -302,16 +302,26 @@ copperplate_setup_call(copperplate_interface); * * @page api-tags API service tags * - * The non-POSIX API services based on the Copperplate library may be - * restricted to particular calling contexts, or entail specific - * side-effects. This information applies to the Alchemy API services, - * and to all RTOS emulators as well. To describe this information, - * each service documented by this section bears a set of tags when - * applicable. + * 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. * * 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 + * 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. + * * @par * <b>Context tags</b> * <TABLE> @@ -325,19 +335,19 @@ copperplate_setup_call(copperplate_interface); * <TR><TD>unrestricted</TD> <TD>May be called from any context previously described</TD></TR> * </TABLE> * - * @note A Xenomai handler is most often used for callback-based - * timeout notifications. This context is @a NOT mapped to a regular - * Linux signal handler, it is actually underlaid by a special thread - * context, so that async-unsafe POSIX services may be invoked - * internally by the API implementation when running on behalf of such - * handler. Therefore, calling Xenomai API services from asynchronous - * regular signal handlers is fundamentally unsafe. - * - * @note A non-blocking call for an API service is defined by a - * special value passed as a timeout specification. + * @note A Xenomai handler is used for callback-based notifications + * from Copperplate-based APIs, such as timeouts. This context is @a + * NOT mapped to a regular Linux signal handler, it is actually + * underlaid by a special thread context, so that async-unsafe POSIX + * services may be invoked internally by the API implementation when + * running on behalf of such handler. Therefore, calling Xenomai API + * services from asynchronous regular signal handlers is fundamentally + * unsafe. * * @par - * <b>Possible side-effects over the Cobalt core (i.e. dual kernel configuration)</b> + * <b>Possible side-effects when running the application over the + * Cobalt core (i.e. dual kernel configuration)</b> + * * <TABLE> * <TR><TH>Tag</TH> <TH>Description</TH></TR> * <TR><TD>switch-primary</TD> <TD>the caller may switch to primary mode</TD></TR> _______________________________________________ Xenomai-git mailing list Xenomai-git@xenomai.org http://xenomai.org/mailman/listinfo/xenomai-git
