Module: xenomai-forge Branch: next Commit: 7f66f9a441a7a88b3f79b46e65c048e63bd4a40a URL: http://git.xenomai.org/?p=xenomai-forge.git;a=commit;h=7f66f9a441a7a88b3f79b46e65c048e63bd4a40a
Author: Philippe Gerum <r...@xenomai.org> Date: Fri Aug 8 09:40:07 2014 +0200 trank: document compatibility wrappers --- lib/trank/native.c | 212 +++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 211 insertions(+), 1 deletion(-) diff --git a/lib/trank/native.c b/lib/trank/native.c index a13eb38..b987f67 100644 --- a/lib/trank/native.c +++ b/lib/trank/native.c @@ -21,6 +21,100 @@ #include <trank/native/alarm.h> #include "../alchemy/alarm.h" +/** + * @ingroup trank + * @{ + */ + +/** + * Create a real-time task (compatibility service). + * + * This service creates a task with access to the full set of Xenomai + * real-time services. + * + * This service creates a task with access to the full set of Xenomai + * real-time services. If @a prio is non-zero, the new task belongs to + * Xenomai's real-time FIFO scheduling class, aka SCHED_FIFO. If @a + * prio is zero, the task belongs to the regular SCHED_OTHER class. + * + * Creating tasks with zero priority is useful for running non + * real-time processes which may invoke blocking real-time services, + * such as pending on a semaphore, reading from a message queue or a + * buffer, and so on. + * + * Once created, the task is left dormant until it is actually started + * by rt_task_start(). + * + * @param task The address of a task descriptor which can be later + * used to identify uniquely the created object, upon success of this + * call. + * + * @param name An ASCII string standing for the symbolic name of the + * task. When non-NULL and non-empty, a copy of this string is + * used for indexing the created task into the object registry. + * + * @param stksize The size of the stack (in bytes) for the new + * task. If zero is passed, a system-dependent default size will be + * substituted. + * + * @param prio The base priority of the new task. This value must be + * in the [0 .. 99] range, where 0 is the lowest effective priority. + * + * @param mode The task creation mode. The following flags can be + * OR'ed into this bitmask: + * + * - T_FPU allows the task to use the FPU whenever available on the + * platform. This flag may be omitted, as it is automatically set when + * a FPU is present on the platform, cleared otherwise. + * + * - T_SUSP causes the task to start in suspended mode. In such a + * case, the thread will have to be explicitly resumed using the + * rt_task_resume() service for its execution to actually begin. + * + * - T_CPU(cpuid) makes the new task affine to CPU # @b cpuid. CPU + * identifiers range from 0 to 7 (inclusive). + * + * - T_JOINABLE allows another task to wait on the termination of the + * new task. rt_task_join() shall be called for this task to clean up + * any resources after its termination. + * + * Passing T_FPU|T_CPU(1) in the @a mode parameter thus creates a task + * with FPU support enabled and which will be affine to CPU #1. + * + * - When running over the Cobalt core, T_WARNSW causes the SIGDEBUG + * signal to be sent to the current task whenever it switches to the + * secondary mode. This feature is useful to detect unwanted + * migrations to the Linux domain. This flag has no effect over the + * Mercury core. + * + * @return Zero is returned upon success. Otherwise: + * + * - -EINVAL is returned if either @a prio, @a mode or @a stksize are + * invalid. + * + * - -ENOMEM is returned if the system fails to get memory from the + * main heap in order to create the task. + * + * - -EEXIST is returned if the @a name is conflicting with an already + * registered task. + * + * @apitags{thread-unrestricted, switch-secondary} + * + * @sideeffect + * + * - calling rt_task_create() causes SCHED_FIFO tasks to switch to + * secondary mode. + * + * - members of Xenomai's SCHED_FIFO class running in the primary + * domain have utmost priority over all Linux activities in the + * system, including Linux interrupt handlers. + * + * @note Tasks can be referred to from multiple processes which all + * belong to the same Xenomai session. + * + * @deprecated This is a compatibility service from the Transition + * Kit. + */ int rt_task_create(RT_TASK *task, const char *name, int stksize, int prio, int mode) { @@ -30,7 +124,7 @@ int rt_task_create(RT_TASK *task, const char *name, susp = mode & T_SUSP; cpus = mode & T_CPUMASK; ret = __CURRENT(rt_task_create(task, name, stksize, prio, - mode & ~(T_SUSP|T_CPUMASK))); + mode & ~(T_SUSP|T_CPUMASK|T_LOCK))); if (ret) return ret; @@ -64,6 +158,56 @@ int rt_task_spawn(RT_TASK *task, const char *name, return rt_task_start(task, entry, arg); } +/** + * Make a real-time task periodic (compatibility service). + * + * Make a task periodic by programing its first release point and its + * period in the processor time line. @a task should then call + * rt_task_wait_period() to sleep until the next periodic release + * point in the processor timeline is reached. + * + * @param task The task descriptor. If @a task is NULL, the current + * task is made periodic. @a task must belong the current process. + * + * @param idate The initial (absolute) date of the first release + * point, expressed in clock ticks (see note). If @a idate is equal + * to TM_NOW, the current system date is used. Otherwise, if @a task + * is NULL or equal to @a rt_task_self(), the caller is delayed until + * @a idate has elapsed. + * + * @param period The period of the task, expressed in clock ticks (see + * note). Passing TM_INFINITE stops the task's periodic timer if + * enabled, then returns successfully. + * + * @return Zero is returned upon success. Otherwise: + * + * - -EINVAL is returned if @a task is NULL but the caller is not a + * Xenomai task, or if @a task is non-NULL but not a valid task + * descriptor. + * + * - -ETIMEDOUT is returned if @a idate is different from TM_INFINITE + * and represents a date in the past. + * + * @apitags{thread-unrestricted, switch-primary} + * + * @note The caller must be an Alchemy task if @a task is NULL. + * + * @note Unlike the original Xenomai 2.x call, this emulation delays + * the caller until @a idate has elapsed only if @a task is NULL or + * equal to rt_task_self(). + * + * @sideeffect Over Cobalt, -EINVAL is returned if @a period is + * different from TM_INFINITE but shorter than the user scheduling + * latency value for the target system, as displayed by + * /proc/xenomai/latency. + * + * @note The @a idate and @a period values are interpreted as a + * multiple of the Alchemy clock resolution (see + * --alchemy-clock-resolution option, defaults to 1 nanosecond). + * + * @deprecated This is a compatibility service from the Transition + * Kit. + */ int rt_task_set_periodic(RT_TASK *task, RTIME idate, RTIME period) { int ret; @@ -98,6 +242,42 @@ static void trank_alarm_handler(void *arg) __RT(pthread_mutex_unlock(&aw->lock)); } +/** + * Create an alarm object (compatibility service). + * + * This routine creates an object triggering an alarm routine at a + * specified time in the future. Alarms can be periodic or oneshot, + * depending on the reload interval value passed to rt_alarm_start(). + * A task can wait for timeouts using the rt_alarm_wait() service. + * + * @param alarm The address of an alarm descriptor which can be later + * used to identify uniquely the created object, upon success of this + * call. + * + * @param name An ASCII string standing for the symbolic name of the + * alarm. When non-NULL and non-empty, a copy of this string is used + * for indexing the created alarm into the object registry. + * + * @return Zero is returned upon success. Otherwise: + * + * - -ENOMEM is returned if the system fails to get memory from the + * local pool in order to create the alarm. + * + * - -EEXIST is returned if the @a name is conflicting with an already + * registered alarm. + * + * - -EPERM is returned if this service was called from an + * asynchronous context. + * + * @apitags{thread-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 + * session. + * + * @deprecated This is a compatibility service from the Transition + * Kit. + */ int rt_alarm_create(RT_ALARM *alarm, const char *name) { struct trank_alarm_wait *aw; @@ -157,6 +337,34 @@ static struct alchemy_alarm *find_alarm(RT_ALARM *alarm) return acb; } +/** + * Wait for the next alarm shot (compatibility service). + * + * This service allows the current task to suspend execution until the + * specified alarm triggers. The priority of the current task is + * raised above all other tasks - except those also undergoing an + * alarm wait. + * + * @return Zero is returned upon success, after the alarm timed + * out. Otherwise: + * + * - -EINVAL is returned if @a alarm is not a valid alarm descriptor. + * + * - -EPERM is returned if this service was called from an invalid + * context. + * + * - -EINTR is returned if rt_task_unblock() was called for the + * current task before the request is satisfied. + * + * - -EIDRM is returned if @a alarm is deleted while the caller was + * sleeping on it. In such a case, @a alarm is no more valid upon + * return of this service. + * + * @apitags{xthread-only, switch-primary} + * + * @deprecated This is a compatibility service from the Transition + * Kit. + */ int rt_alarm_wait(RT_ALARM *alarm) { struct threadobj *current = threadobj_current(); @@ -221,3 +429,5 @@ int rt_alarm_delete(RT_ALARM *alarm) return 0; } + +/** @} */ _______________________________________________ Xenomai-git mailing list Xenomai-git@xenomai.org http://www.xenomai.org/mailman/listinfo/xenomai-git