Module: xenomai-forge
Branch: next
Commit: 947778d26e4dc21c831f4e7c826289892dbe1285
URL:    
http://git.xenomai.org/?p=xenomai-forge.git;a=commit;h=947778d26e4dc21c831f4e7c826289892dbe1285

Author: Philippe Gerum <r...@xenomai.org>
Date:   Wed Jun 11 19:59:31 2014 +0200

doc: general fixup of the doxygen-based contents hierarchy (WIP)

---

 doc/doxygen/manual-common.conf.in   |   44 +---
 include/cobalt/kernel/rtdm/driver.h |  445 ++++-------------------------------
 kernel/cobalt/rtdm/core.c           |  412 +++++++++++++++++++++++++++++++-
 kernel/cobalt/rtdm/device.c         |    4 +-
 kernel/cobalt/rtdm/drvlib.c         |   29 ++-
 5 files changed, 478 insertions(+), 456 deletions(-)

diff --git a/doc/doxygen/manual-common.conf.in 
b/doc/doxygen/manual-common.conf.in
index 0279a65..11c3893 100644
--- a/doc/doxygen/manual-common.conf.in
+++ b/doc/doxygen/manual-common.conf.in
@@ -657,11 +657,7 @@ INCLUDE_FILE_PATTERNS  =
 # omitted =1 is assumed.
 
 PREDEFINED = DOXYGEN_CPP \
-        EXPORT_SYMBOL_GPL(symbol)=// \
-       __KERNEL__ \
-        CONFIG_XENO_OPT_PIPE \
-        CONFIG_XENO_OPT_REGISTRY \
-        CONFIG_XENO_OPT_RTDM_SELECT
+        EXPORT_SYMBOL_GPL(symbol)=//
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then 
 # this tag can be used to specify a list of macro names that should be 
expanded. 
@@ -866,44 +862,6 @@ INPUT                  =                                   
        \
                       @top_srcdir@/lib/analogy                         \
                       @top_srcdir@/lib/alchemy
 
-# INPUT                  =                                             \
-#                     @top_srcdir@/include/cobalt                      \
-#                     @top_srcdir@/include/cobalt/kernel               \
-#                     @top_srcdir@/include/cobalt/kernel/rtdm          \
-#                     @top_srcdir@/include/cobalt/kernel/rtdm/analogy  \
-#                     @top_srcdir@/include/cobalt/sys                  \
-#                     @top_srcdir@/include/cobalt/uapi                 \
-#                     @top_srcdir@/include/cobalt/uapi/kernel          \
-#                     @top_srcdir@/include/cobalt/uapi/rtdm            \
-#                     @top_srcdir@/include/boilerplate                 \
-#                     @top_srcdir@/include/copperplate                 \
-#                     @top_srcdir@/include/alchemy                     \
-#                     @top_srcdir@/include/vxworks                     \
-#                     @top_srcdir@/include/psos                        \
-#                     @top_srcdir@/include/rtdm                        \
-#                     @top_srcdir@/include/rtdm/uapi                   \
-#                     @top_srcdir@/kernel/cobalt                       \
-#                     @top_srcdir@/kernel/cobalt/arch/arm              \
-#                     @top_srcdir@/kernel/cobalt/arch/powerpc          \
-#                     @top_srcdir@/kernel/cobalt/arch/x86              \
-#                     @top_srcdir@/kernel/cobalt/arch/blackfin         \
-#                     @top_srcdir@/kernel/cobalt/arch/nios2            \
-#                     @top_srcdir@/kernel/cobalt/arch/sh               \
-#                     @top_srcdir@/kernel/cobalt/rtdm                  \
-#                     @top_srcdir@/kernel/cobalt/posix                 \
-#                     @top_srcdir@/kernel/drivers/ipc                  \
-#                     @top_srcdir@/kernel/drivers/serial               \
-#                     @top_srcdir@/kernel/drivers/analogy              \
-#                     @top_srcdir@/kernel/drivers/can                  \
-#                     @top_srcdir@/kernel/drivers/testing              \
-#                     @top_srcdir@/lib/boilerplate                     \
-#                     @top_srcdir@/lib/cobalt                          \
-#                     @top_srcdir@/lib/analogy                         \
-#                     @top_srcdir@/lib/copperplate                     \
-#                     @top_srcdir@/lib/alchemy                         \
-#                     @top_srcdir@/lib/psos                            \
-#                     @top_srcdir@/lib/vxworks
-
 # The EXAMPLE_PATH tag can be used to specify one or more files or
 # directories that contain example code fragments that are included (see
 # the \include command).
diff --git a/include/cobalt/kernel/rtdm/driver.h 
b/include/cobalt/kernel/rtdm/driver.h
index 68bcabc..13668e9 100644
--- a/include/cobalt/kernel/rtdm/driver.h
+++ b/include/cobalt/kernel/rtdm/driver.h
@@ -398,13 +398,55 @@ void rtdm_toseq_init(rtdm_toseq_t *timeout_seq, 
nanosecs_rel_t timeout);
  * @{
  */
 
-/* --- spin lock services --- */
 /*!
- * @name Global Lock across Scheduler Invocation
+ * @defgroup rtdm_sync_biglock Big dual kernel lock
  * @{
  */
 
 /**
+ * @brief Enter atomic section (dual kernel only)
+ *
+ * This call opens a fully atomic section, serializing execution with
+ * respect to all interrupt handlers (including for real-time IRQs)
+ * and Xenomai threads running on all CPUs.
+ *
+ * @param context name of local variable to store the context in. This
+ * variable updated by the real-time core will hold the information
+ * required to leave the atomic section properly.
+ *
+ * @note Atomic sections may be nested.
+ *
+ * @note Since the strongest lock is acquired by this service, it can
+ * be used to synchronize real-time and non-real-time contexts.
+ *
+ * @warning This service is not portable to the Mercury core, and
+ * should be restricted to Cobalt-specific use cases.
+ */
+#define cobalt_atomic_enter(context)                   \
+       do {                                            \
+               xnlock_get_irqsave(&nklock, (context)); \
+               __xnsched_lock();                       \
+       } while (0)
+
+/**
+ * @brief Leave atomic section (dual kernel only)
+ *
+ * This call closes an atomic section previously opened by a call to
+ * cobalt_atomic_enter(), restoring the preemption and interrupt state
+ * which prevailed prior to entering the exited section.
+ *
+ * @param context name of local variable which stored the context.
+ *
+ * @warning This service is not portable to the Mercury core, and
+ * should be restricted to Cobalt-specific use cases.
+ */
+#define cobalt_atomic_leave(context)                           \
+       do {                                                    \
+               __xnsched_unlock();                             \
+               xnlock_put_irqrestore(&nklock, (context));      \
+       } while (0)
+
+/**
  * @brief Execute code block atomically (DEPRECATED)
  *
  * Generally, it is illegal to suspend the current task by calling
@@ -463,10 +505,10 @@ rtdm_execute_atomically(void) { }
 }
 #endif
 
-/** @} Global Lock across Scheduler Invocation */
+/** @} Big dual kernel lock */
 
-/*!
- * @name Spinlock with Preemption Deactivation
+/**
+ * @defgroup rtdm_sync_spinlock Spinlock with preemption deactivation
  * @{
  */
 
@@ -643,55 +685,10 @@ void rtdm_lock_put_irqrestore(rtdm_lock_t *lock, 
rtdm_lockctx_t context)
 #define rtdm_lock_irqrestore(context)  \
        splexit(context)
 
-/**
- * @brief Enter atomic section (dual kernel only)
- *
- * This call opens a fully atomic section, serializing execution with
- * respect to all interrupt handlers (including for real-time IRQs)
- * and Xenomai threads running on all CPUs.
- *
- * @param context name of local variable to store the context in. This
- * variable updated by the real-time core will hold the information
- * required to leave the atomic section properly.
- *
- * @note Atomic sections may be nested.
- *
- * @note Since the strongest lock is acquired by this service, it can
- * be used to synchronize real-time and non-real-time contexts.
- *
- * @warning This service is not portable to the Mercury core, and
- * should be restricted to Cobalt-specific use cases.
- */
-#define cobalt_atomic_enter(context)                   \
-       do {                                            \
-               xnlock_get_irqsave(&nklock, (context)); \
-               __xnsched_lock();                       \
-       } while (0)
-
-/**
- * @brief Leave atomic section (dual kernel only)
- *
- * This call closes an atomic section previously opened by a call to
- * cobalt_atomic_enter(), restoring the preemption and interrupt state
- * which prevailed prior to entering the exited section.
- *
- * @param context name of local variable which stored the context.
- *
- * @warning This service is not portable to the Mercury core, and
- * should be restricted to Cobalt-specific use cases.
- */
-#define cobalt_atomic_leave(context)                           \
-       do {                                                    \
-               __xnsched_unlock();                             \
-               xnlock_put_irqrestore(&nklock, (context));      \
-       } while (0)
-
 /** @} Spinlock with Preemption Deactivation */
 
-/*!
- * @name Signal, test and wait for a condition atomically
- * @{
- */
+#ifndef DOXYGEN_CPP
+
 struct rtdm_waitqueue {
        struct xnsynch wait;
 };
@@ -707,28 +704,11 @@ typedef struct rtdm_waitqueue rtdm_waitqueue_t;
 #define DEFINE_RTDM_WAITQUEUE_ONSTACK(__name)  \
        DEFINE_RTDM_WAITQUEUE(__name)
 
-/**
- * @fn void rtdm_waitqueue_init(struct rtdm_waitqueue *wq)
- * @brief  Initialize a RTDM wait queue
- *
- * Sets up a wait queue structure for further use.
- *
- * @param wq waitqueue to initialize.
- */
 static inline void rtdm_waitqueue_init(struct rtdm_waitqueue *wq)
 {
        *wq = (struct rtdm_waitqueue)RTDM_WAITQUEUE_INITIALIZER(*wq);
 }
 
-/**
- * @fn void rtdm_waitqueue_destroy(struct rtdm_waitqueue *wq)
- * @brief  Deletes a RTDM wait queue
- *
- * Dismantles a wait queue structure, releasing all resources attached
- * to it.
- *
- * @param wq waitqueue to delete.
- */
 static inline void rtdm_waitqueue_destroy(struct rtdm_waitqueue *wq)
 {
        xnsynch_destroy(&wq->wait);
@@ -743,43 +723,6 @@ static inline int __rtdm_timedwait(struct rtdm_waitqueue 
*wq,
        return xnsynch_sleep_on(&wq->wait, timeout, XN_RELATIVE);
 }
 
-/**
- * @fn rtdm_timedwait_condition_locked(struct rtdm_wait_queue *wq, condition, 
nanosecs_rel_t timeout, rtdm_toseq_t *toseq)
- * @brief Timed sleep on a locked waitqueue until a condition gets true
- *
- * The calling task is put to sleep until @a condition evaluates to
- * true or a timeout occurs. The condition is checked each time the
- * waitqueue @a wq is signaled.
- *
- * The waitqueue must have been locked by a call to
- * rtdm_waitqueue_lock() prior to calling this service.
- *
- * @param wq locked waitqueue to wait on. The waitqueue lock is
- * dropped when sleeping, then reacquired before this service returns
- * to the caller.
- *
- * @param condition C expression for the event to wait for.
- *
- * @param timeout relative timeout in nanoseconds, see
- * @ref RTDM_TIMEOUT_xxx for special values.
- * 
- * @param[in,out] toseq handle of a timeout sequence as returned by
- * rtdm_toseq_init() or NULL.
- *
- * @return 0 on success, otherwise:
- *
- * - -EINTR is returned if calling task has received a Linux signal or
- * has been forcibly unblocked by a call to rtdm_task_unblock().
- *
- * - -ETIMEDOUT is returned if the if the request has not been satisfied
- * within the specified amount of time.
- *
- * @note rtdm_waitqueue_signal() has to be called after changing any
- * variable that could change the result of the wait condition.
- *
- * @note Passing RTDM_TIMEOUT_NONE to @a timeout makes no sense for
- * such service, and might cause unexpected behavior.
- */
 #define rtdm_timedwait_condition_locked(__wq, __cond, __timeout, __toseq) \
        ({                                                              \
                int __ret = 0;                                          \
@@ -788,31 +731,6 @@ static inline int __rtdm_timedwait(struct rtdm_waitqueue 
*wq,
                __ret;                                                  \
        })
 
-/**
- * @fn rtdm_wait_condition_locked(struct rtdm_wait_queue *wq, condition)
- * @brief Sleep on a locked waitqueue until a condition gets true
- *
- * The calling task is put to sleep until @a condition evaluates to
- * true. The condition is checked each time the waitqueue @a wq is
- * signaled.
- *
- * The waitqueue must have been locked by a call to
- * rtdm_waitqueue_lock() prior to calling this service.
- *
- * @param wq locked waitqueue to wait on. The waitqueue lock is
- * dropped when sleeping, then reacquired before this service returns
- * to the caller.
- *
- * @param cond C expression for the event to wait for.
- *
- * @return 0 on success, otherwise:
- *
- * - -EINTR is returned if calling task has received a Linux signal or
- * has been forcibly unblocked by a call to rtdm_task_unblock().
- *
- * @note rtdm_waitqueue_signal() has to be called after changing any
- * variable that could change the result of the wait condition.
- */
 #define rtdm_wait_condition_locked(__wq, __cond)                       \
        ({                                                              \
                int __ret = 0;                                          \
@@ -822,38 +740,6 @@ static inline int __rtdm_timedwait(struct rtdm_waitqueue 
*wq,
                __ret;                                                  \
        })
 
-/**
- * @fn rtdm_timedwait_condition(struct rtdm_wait_queue *wq, condition, 
nanosecs_rel_t timeout, rtdm_toseq_t *toseq)
- * @brief Timed sleep on a waitqueue until a condition gets true
- *
- * The calling task is put to sleep until @a condition evaluates to
- * true or a timeout occurs. The condition is checked each time the
- * waitqueue @a wq is signaled.
- *
- * @param wq waitqueue to wait on.
- *
- * @param cond C expression for the event to wait for.
- *
- * @param timeout relative timeout in nanoseconds, see
- * @ref RTDM_TIMEOUT_xxx for special values.
- * 
- * @param[in,out] toseq handle of a timeout sequence as returned by
- * rtdm_toseq_init() or NULL.
- *
- * @return 0 on success, otherwise:
- *
- * - -EINTR is returned if calling task has received a Linux signal or
- * has been forcibly unblocked by a call to rtdm_task_unblock().
- *
- * - -ETIMEDOUT is returned if the if the request has not been satisfied
- * within the specified amount of time.
- *
- * @note rtdm_waitqueue_signal() has to be called after changing any
- * variable that could change the result of the wait condition.
- *
- * @note Passing RTDM_TIMEOUT_NONE to @a timeout makes no sense for
- * such service, and might cause unexpected behavior.
- */
 #define rtdm_timedwait_condition(__wq, __cond, __timeout, __toseq)     \
        ({                                                              \
                spl_t __s;                                              \
@@ -865,93 +751,12 @@ static inline int __rtdm_timedwait(struct rtdm_waitqueue 
*wq,
                __ret;                                                  \
        })
 
-/**
- * @fn rtdm_timedwait(struct rtdm_wait_queue *wq, nanosecs_rel_t timeout, 
rtdm_toseq_t *toseq)
- * @brief Timed sleep on a waitqueue unconditionally
- *
- * The calling task is put to sleep until the waitqueue is signaled by
- * either rtdm_waitqueue_signal() or rtdm_waitqueue_broadcast(), or
- * flushed by a call to rtdm_waitqueue_flush(), or a timeout occurs.
- *
- * @param wq waitqueue to wait on.
- *
- * @param timeout relative timeout in nanoseconds, see
- * @ref RTDM_TIMEOUT_xxx for special values.
- * 
- * @param[in,out] toseq handle of a timeout sequence as returned by
- * rtdm_toseq_init() or NULL.
- *
- * @return 0 on success, otherwise:
- *
- * - -EINTR is returned if the waitqueue has been flushed, or the
- * calling task has received a Linux signal or has been forcibly
- * unblocked by a call to rtdm_task_unblock().
- *
- * - -ETIMEDOUT is returned if the if the request has not been satisfied
- * within the specified amount of time.
- *
- * @note Passing RTDM_TIMEOUT_NONE to @a timeout makes no sense for
- * such service, and might cause unexpected behavior.
- */
 #define rtdm_timedwait(__wq, __timeout, __toseq)                       \
        __rtdm_timedwait(__wq, __timeout, __toseq)
 
-/**
- * @fn rtdm_timedwait_locked(struct rtdm_wait_queue *wq, nanosecs_rel_t 
timeout, rtdm_toseq_t *toseq)
- * @brief Timed sleep on a locked waitqueue unconditionally
- *
- * The calling task is put to sleep until the waitqueue is signaled by
- * either rtdm_waitqueue_signal() or rtdm_waitqueue_broadcast(), or
- * flushed by a call to rtdm_waitqueue_flush(), or a timeout occurs.
- *
- * The waitqueue must have been locked by a call to
- * rtdm_waitqueue_lock() prior to calling this service.
- *
- * @param wq locked waitqueue to wait on. The waitqueue lock is
- * dropped when sleeping, then reacquired before this service returns
- * to the caller.
- *
- * @param timeout relative timeout in nanoseconds, see
- * @ref RTDM_TIMEOUT_xxx for special values.
- * 
- * @param[in,out] toseq handle of a timeout sequence as returned by
- * rtdm_toseq_init() or NULL.
- *
- * @return 0 on success, otherwise:
- *
- * - -EINTR is returned if the waitqueue has been flushed, or the
- * calling task has received a Linux signal or has been forcibly
- * unblocked by a call to rtdm_task_unblock().
- *
- * - -ETIMEDOUT is returned if the if the request has not been satisfied
- * within the specified amount of time.
- *
- * @note Passing RTDM_TIMEOUT_NONE to @a timeout makes no sense for
- * such service, and might cause unexpected behavior.
- */
 #define rtdm_timedwait_locked(__wq, __timeout, __toseq)                        
\
        rtdm_timedwait(__wq, __timeout, __toseq)
 
-/**
- * @fn rtdm_wait_condition(struct rtdm_wait_queue *wq, condition)
- * @brief Sleep on a waitqueue until a condition gets true
- *
- * The calling task is put to sleep until @a condition evaluates to
- * true. The condition is checked each time the waitqueue @a wq is
- * signaled.
- *
- * @param wq waitqueue to wait on
- *
- * @param condition C expression for the event to wait for.
- *
- * @return 0 on success, otherwise:
- *
- * - -EINTR is returned if calling task has received a Linux signal or
- * has been forcibly unblocked by a call to rtdm_task_unblock().
- *
- * @note rtdm_waitqueue_signal() has to be called after changing any
- * variable that could change the result of the wait condition.
- */
 #define rtdm_wait_condition(__wq, __cond)                              \
        ({                                                              \
                spl_t __s;                                              \
@@ -962,87 +767,15 @@ static inline int __rtdm_timedwait(struct rtdm_waitqueue 
*wq,
                __ret;                                                  \
        })
 
-/**
- * @fn rtdm_wait(struct rtdm_wait_queue *wq)
- * @brief Sleep on a waitqueue unconditionally
- *
- * The calling task is put to sleep until the waitqueue is signaled by
- * either rtdm_waitqueue_signal() or rtdm_waitqueue_broadcast(), or
- * flushed by a call to rtdm_waitqueue_flush().
- *
- * @param wq waitqueue to wait on.
- *
- * @return 0 on success, otherwise:
- *
- * - -EINTR is returned if the waitqueue has been flushed, or the
- * calling task has received a Linux signal or has been forcibly
- * unblocked by a call to rtdm_task_unblock().
- */
 #define rtdm_wait(__wq)                                                        
\
        xnsynch_sleep_on(&(__wq)->wait, XN_INFINITE, XN_RELATIVE)
 
-/**
- * @fn rtdm_wait_locked(struct rtdm_wait_queue *wq)
- * @brief Sleep on a locked waitqueue unconditionally
- *
- * The calling task is put to sleep until the waitqueue is signaled by
- * either rtdm_waitqueue_signal() or rtdm_waitqueue_broadcast(), or
- * flushed by a call to rtdm_waitqueue_flush().
- *
- * The waitqueue must have been locked by a call to
- * rtdm_waitqueue_lock() prior to calling this service.
- *
- * @param wq locked waitqueue to wait on. The waitqueue lock is
- * dropped when sleeping, then reacquired before this service returns
- * to the caller.
- *
- * @return 0 on success, otherwise:
- *
- * - -EINTR is returned if the waitqueue has been flushed, or the
- * calling task has received a Linux signal or has been forcibly
- * unblocked by a call to rtdm_task_unblock().
- */
 #define rtdm_wait_locked(__wq)  rtdm_wait(__wq)
 
-/**
- * @fn rtdm_waitqueue_lock(struct rtdm_wait_queue *wq, rtdm_lockctx_t context)
- * @brief Lock a waitqueue
- *
- * Acquires the lock on the waitqueue @a wq.
- *
- * @param wq waitqueue to lock.
- *
- * @param context name of local variable to store the context in.
- *
- * @note Recursive locking might lead to unexpected behavior,
- * including lock up.
- */
 #define rtdm_waitqueue_lock(__wq, __context)  cobalt_atomic_enter(__context)
 
-/**
- * @fn rtdm_waitqueue_unlock(struct rtdm_wait_queue *wq, rtdm_lockctx_t 
context)
- * @brief Unlock a waitqueue
- *
- * Releases the lock on the waitqueue @a wq.
- *
- * @param wq waitqueue to unlock.
- *
- * @param context name of local variable to retrieve the context from.
- */
 #define rtdm_waitqueue_unlock(__wq, __context)  cobalt_atomic_leave(__context)
 
-/**
- * @fn rtdm_waitqueue_signal(struct rtdm_wait_queue *wq)
- * @brief Signal a waitqueue
- *
- * Signals the waitqueue @a wq, waking up a single waiter (if
- * any).
- *
- * @param wq waitqueue to signal.
- *
- * @return non-zero if a task has been readied as a result of this
- * call, zero otherwise.
- */
 #define rtdm_waitqueue_signal(__wq)                                    \
        ({                                                              \
                struct xnthread *__waiter;                              \
@@ -1059,103 +792,25 @@ static inline int __rtdm_timedwait(struct 
rtdm_waitqueue *wq,
                __ret == XNSYNCH_RESCHED;                               \
        })
 
-/**
- * @fn rtdm_waitqueue_broadcast(struct rtdm_wait_queue *wq)
- * @brief Broadcast a waitqueue
- *
- * Broadcast the waitqueue @a wq, waking up all waiters. Each
- * readied task may assume to have received the wake up event.
- *
- * @param wq waitqueue to broadcast.
- *
- * @return non-zero if at least one task has been readied as a result
- * of this call, zero otherwise.
- */
 #define rtdm_waitqueue_broadcast(__wq) \
        __rtdm_waitqueue_flush(__wq, 0)
 
-/**
- * @fn rtdm_waitqueue_flush(struct rtdm_wait_queue *wq)
- * @brief Flush a waitqueue
- *
- * Flushes the waitqueue @a wq, unblocking all waiters with an error
- * status (-EINTR).
- *
- * @param wq waitqueue to flush.
- *
- * @return non-zero if at least one task has been readied as a result
- * of this call, zero otherwise.
- */
 #define rtdm_waitqueue_flush(__wq)     \
        __rtdm_waitqueue_flush(__wq, XNBREAK)
 
-/**
- * @fn rtdm_waitqueue_wakeup(struct rtdm_wait_queue *wq, rtdm_task_t waiter)
- * @brief Signal a particular waiter on a waitqueue
- *
- * Signals the waitqueue @a wq, waking up waiter @a waiter only,
- * which must be currently sleeping on the waitqueue.
- *
- * @param wq waitqueue to signal.
- *
- * @param waiter RTDM task to wake up.
- */
 #define rtdm_waitqueue_wakeup(__wq, __waiter)                          \
        do {                                                            \
                xnsynch_wakeup_this_sleeper(&(__wq)->wait, __waiter);   \
                xnsched_run();                                          \
        } while (0)
 
-/**
- * @fn rtdm_for_each_waiter(rtdm_task_t pos, struct rtdm_wait_queue *wq)
- * @brief Simple iterator for waitqueues
- *
- * This construct traverses the wait list of a given waitqueue
- * @a wq, assigning each RTDM task pointer to the cursor variable
- * @a pos, which must be of type rtdm_task_t.
- *
- * @a wq must have been locked by a call to rtdm_waitqueue_lock()
- * prior to traversing its wait list.
- *
- * @param pos cursor variable holding a pointer to the RTDM task
- * being fetched.
- *
- * @param wq waitqueue to scan.
- *
- * @note The waitqueue should not be signaled, broadcast or flushed
- * during the traversal, unless the loop is aborted immediately
- * after. Should multiple waiters be readied while iterating, the safe
- * form rtdm_for_each_waiter_safe() must be used for traversal
- * instead.
- */
 #define rtdm_for_each_waiter(__pos, __wq)              \
        xnsynch_for_each_sleeper(__pos, &(__wq)->wait)
 
-/**
- * @fn rtdm_for_each_waiter_safe(rtdm_task_t pos, rtdm_task_t tmp, struct 
rtdm_wait_queue *wq)
- * @brief Safe iterator for waitqueues
- *
- * This construct traverses the wait list of a given waitqueue
- * @a wq, assigning each RTDM task pointer to the cursor variable
- * @a pos, which must be of type rtdm_task_t.
- *
- * Unlike with rtdm_for_each_waiter(), the waitqueue may be signaled,
- * broadcast or flushed during the traversal.
- *
- * @a wq must have been locked by a call to rtdm_waitqueue_lock()
- * prior to traversing its wait list.
- *
- * @param pos cursor variable holding a pointer to the RTDM task
- * being fetched.
- *
- * @param tmp temporary cursor variable.
- *
- * @param wq waitqueue to scan.
- */
 #define rtdm_for_each_waiter_safe(__pos, __tmp, __wq)  \
        xnsynch_for_each_sleeper_safe(__pos, __tmp, &(__wq)->wait)
 
-/** @} Signal, test and wait for a condition atomically */
+#endif /* !DOXYGEN_CPP */
 
 /** @} rtdm_sync */
 
diff --git a/kernel/cobalt/rtdm/core.c b/kernel/cobalt/rtdm/core.c
index 90d6eaf..37e6901 100644
--- a/kernel/cobalt/rtdm/core.c
+++ b/kernel/cobalt/rtdm/core.c
@@ -32,8 +32,8 @@
 
 /**
  * @ingroup rtdm
- * @defgroup rtdm_driver_api Inter-Driver API
- * RTDM driver-to-driver interface
+ * @defgroup rtdm_driver_interface Driver programming interface
+ * RTDM driver programming interface
  * @{
  */
 
@@ -240,6 +240,11 @@ __rt_dev_ioctl_fallback(struct rtdm_fd *fd, unsigned int 
request, void __user *a
 #ifdef DOXYGEN_CPP /* Only used for doxygen doc generation */
 
 /**
+ * @addtogroup rtdm_sync
+ *@{
+ */
+
+/**
  * @brief Increment context reference counter
  *
  * @param[in] context Device context
@@ -307,6 +312,405 @@ void rtdm_context_unlock(struct rtdm_dev_context 
*context);
 void rtdm_context_put(struct rtdm_dev_context *context);
 
 /**
+ * @ingroup rtdm_sync
+ * @defgroup rtdm_sync_wq Wait queue
+ * RTDM wait queues
+ * @{
+ */
+
+/**
+ * @fn void rtdm_waitqueue_init(struct rtdm_waitqueue *wq)
+ * @brief  Initialize a RTDM wait queue
+ *
+ * Sets up a wait queue structure for further use.
+ *
+ * @param wq waitqueue to initialize.
+ */
+void rtdm_waitqueue_init(struct rtdm_waitqueue *wq);
+
+/**
+ * @fn void rtdm_waitqueue_destroy(struct rtdm_waitqueue *wq)
+ * @brief  Deletes a RTDM wait queue
+ *
+ * Dismantles a wait queue structure, releasing all resources attached
+ * to it.
+ *
+ * @param wq waitqueue to delete.
+ */
+void rtdm_waitqueue_destroy(struct rtdm_waitqueue *wq);
+
+/**
+ * @fn rtdm_timedwait_condition_locked(struct rtdm_wait_queue *wq, C_expr 
condition, nanosecs_rel_t timeout, rtdm_toseq_t *toseq)
+ * @brief Timed sleep on a locked waitqueue until a condition gets true
+ *
+ * The calling task is put to sleep until @a condition evaluates to
+ * true or a timeout occurs. The condition is checked each time the
+ * waitqueue @a wq is signaled.
+ *
+ * The waitqueue must have been locked by a call to
+ * rtdm_waitqueue_lock() prior to calling this service.
+ *
+ * @param wq locked waitqueue to wait on. The waitqueue lock is
+ * dropped when sleeping, then reacquired before this service returns
+ * to the caller.
+ *
+ * @param condition C expression for the event to wait for.
+ *
+ * @param timeout relative timeout in nanoseconds, see
+ * @ref RTDM_TIMEOUT_xxx for special values.
+ * 
+ * @param[in,out] toseq handle of a timeout sequence as returned by
+ * rtdm_toseq_init() or NULL.
+ *
+ * @return 0 on success, otherwise:
+ *
+ * - -EINTR is returned if calling task has received a Linux signal or
+ * has been forcibly unblocked by a call to rtdm_task_unblock().
+ *
+ * - -ETIMEDOUT is returned if the if the request has not been satisfied
+ * within the specified amount of time.
+ *
+ * @note rtdm_waitqueue_signal() has to be called after changing any
+ * variable that could change the result of the wait condition.
+ *
+ * @note Passing RTDM_TIMEOUT_NONE to @a timeout makes no sense for
+ * such service, and might cause unexpected behavior.
+ */
+rtdm_timedwait_condition_locked(struct rtdm_wait_queue *wq, C_expr condition,
+                               nanosecs_rel_t timeout, rtdm_toseq_t *toseq);
+
+/**
+ * @fn rtdm_wait_condition_locked(struct rtdm_wait_queue *wq, C_expr condition)
+ * @brief Sleep on a locked waitqueue until a condition gets true
+ *
+ * The calling task is put to sleep until @a condition evaluates to
+ * true. The condition is checked each time the waitqueue @a wq is
+ * signaled.
+ *
+ * The waitqueue must have been locked by a call to
+ * rtdm_waitqueue_lock() prior to calling this service.
+ *
+ * @param wq locked waitqueue to wait on. The waitqueue lock is
+ * dropped when sleeping, then reacquired before this service returns
+ * to the caller.
+ *
+ * @param condition C expression for the event to wait for.
+ *
+ * @return 0 on success, otherwise:
+ *
+ * - -EINTR is returned if calling task has received a Linux signal or
+ * has been forcibly unblocked by a call to rtdm_task_unblock().
+ *
+ * @note rtdm_waitqueue_signal() has to be called after changing any
+ * variable that could change the result of the wait condition.
+ */
+rtdm_wait_condition_locked(struct rtdm_wait_queue *wq, C_expr condition);
+
+/**
+ * @fn rtdm_timedwait_condition(struct rtdm_wait_queue *wq, C_expr condition, 
nanosecs_rel_t timeout, rtdm_toseq_t *toseq)
+ * @brief Timed sleep on a waitqueue until a condition gets true
+ *
+ * The calling task is put to sleep until @a condition evaluates to
+ * true or a timeout occurs. The condition is checked each time the
+ * waitqueue @a wq is signaled.
+ *
+ * @param wq waitqueue to wait on.
+ *
+ * @param condition C expression for the event to wait for.
+ *
+ * @param timeout relative timeout in nanoseconds, see
+ * @ref RTDM_TIMEOUT_xxx for special values.
+ * 
+ * @param[in,out] toseq handle of a timeout sequence as returned by
+ * rtdm_toseq_init() or NULL.
+ *
+ * @return 0 on success, otherwise:
+ *
+ * - -EINTR is returned if calling task has received a Linux signal or
+ * has been forcibly unblocked by a call to rtdm_task_unblock().
+ *
+ * - -ETIMEDOUT is returned if the if the request has not been satisfied
+ * within the specified amount of time.
+ *
+ * @note rtdm_waitqueue_signal() has to be called after changing any
+ * variable that could change the result of the wait condition.
+ *
+ * @note Passing RTDM_TIMEOUT_NONE to @a timeout makes no sense for
+ * such service, and might cause unexpected behavior.
+ */
+rtdm_timedwait_condition(struct rtdm_wait_queue *wq, C_expr condition,
+                        nanosecs_rel_t timeout, rtdm_toseq_t *toseq);
+
+/**
+ * @fn void rtdm_timedwait(struct rtdm_wait_queue *wq, nanosecs_rel_t timeout, 
rtdm_toseq_t *toseq)
+ * @brief Timed sleep on a waitqueue unconditionally
+ *
+ * The calling task is put to sleep until the waitqueue is signaled by
+ * either rtdm_waitqueue_signal() or rtdm_waitqueue_broadcast(), or
+ * flushed by a call to rtdm_waitqueue_flush(), or a timeout occurs.
+ *
+ * @param wq waitqueue to wait on.
+ *
+ * @param timeout relative timeout in nanoseconds, see
+ * @ref RTDM_TIMEOUT_xxx for special values.
+ * 
+ * @param[in,out] toseq handle of a timeout sequence as returned by
+ * rtdm_toseq_init() or NULL.
+ *
+ * @return 0 on success, otherwise:
+ *
+ * - -EINTR is returned if the waitqueue has been flushed, or the
+ * calling task has received a Linux signal or has been forcibly
+ * unblocked by a call to rtdm_task_unblock().
+ *
+ * - -ETIMEDOUT is returned if the if the request has not been satisfied
+ * within the specified amount of time.
+ *
+ * @note Passing RTDM_TIMEOUT_NONE to @a timeout makes no sense for
+ * such service, and might cause unexpected behavior.
+ */
+void rtdm_timedwait(struct rtdm_wait_queue *wq,
+                   nanosecs_rel_t timeout, rtdm_toseq_t *toseq);
+
+/**
+ * @fn void rtdm_timedwait_locked(struct rtdm_wait_queue *wq, nanosecs_rel_t 
timeout, rtdm_toseq_t *toseq)
+ * @brief Timed sleep on a locked waitqueue unconditionally
+ *
+ * The calling task is put to sleep until the waitqueue is signaled by
+ * either rtdm_waitqueue_signal() or rtdm_waitqueue_broadcast(), or
+ * flushed by a call to rtdm_waitqueue_flush(), or a timeout occurs.
+ *
+ * The waitqueue must have been locked by a call to
+ * rtdm_waitqueue_lock() prior to calling this service.
+ *
+ * @param wq locked waitqueue to wait on. The waitqueue lock is
+ * dropped when sleeping, then reacquired before this service returns
+ * to the caller.
+ *
+ * @param timeout relative timeout in nanoseconds, see
+ * @ref RTDM_TIMEOUT_xxx for special values.
+ * 
+ * @param[in,out] toseq handle of a timeout sequence as returned by
+ * rtdm_toseq_init() or NULL.
+ *
+ * @return 0 on success, otherwise:
+ *
+ * - -EINTR is returned if the waitqueue has been flushed, or the
+ * calling task has received a Linux signal or has been forcibly
+ * unblocked by a call to rtdm_task_unblock().
+ *
+ * - -ETIMEDOUT is returned if the if the request has not been satisfied
+ * within the specified amount of time.
+ *
+ * @note Passing RTDM_TIMEOUT_NONE to @a timeout makes no sense for
+ * such service, and might cause unexpected behavior.
+ */
+void rtdm_timedwait_locked(struct rtdm_wait_queue *wq,
+                          nanosecs_rel_t timeout, rtdm_toseq_t *toseq);
+
+/**
+ * @fn rtdm_wait_condition(struct rtdm_wait_queue *wq, C_expr condition)
+ * @brief Sleep on a waitqueue until a condition gets true
+ *
+ * The calling task is put to sleep until @a condition evaluates to
+ * true. The condition is checked each time the waitqueue @a wq is
+ * signaled.
+ *
+ * @param wq waitqueue to wait on
+ *
+ * @param condition C expression for the event to wait for.
+ *
+ * @return 0 on success, otherwise:
+ *
+ * - -EINTR is returned if calling task has received a Linux signal or
+ * has been forcibly unblocked by a call to rtdm_task_unblock().
+ *
+ * @note rtdm_waitqueue_signal() has to be called after changing any
+ * variable that could change the result of the wait condition.
+ */
+rtdm_wait_condition(struct rtdm_wait_queue *wq, C_expr condition);
+
+/**
+ * @fn void rtdm_wait(struct rtdm_wait_queue *wq)
+ * @brief Sleep on a waitqueue unconditionally
+ *
+ * The calling task is put to sleep until the waitqueue is signaled by
+ * either rtdm_waitqueue_signal() or rtdm_waitqueue_broadcast(), or
+ * flushed by a call to rtdm_waitqueue_flush().
+ *
+ * @param wq waitqueue to wait on.
+ *
+ * @return 0 on success, otherwise:
+ *
+ * - -EINTR is returned if the waitqueue has been flushed, or the
+ * calling task has received a Linux signal or has been forcibly
+ * unblocked by a call to rtdm_task_unblock().
+ */
+void rtdm_wait(struct rtdm_wait_queue *wq);
+
+/**
+ * @fn void rtdm_wait_locked(struct rtdm_wait_queue *wq)
+ * @brief Sleep on a locked waitqueue unconditionally
+ *
+ * The calling task is put to sleep until the waitqueue is signaled by
+ * either rtdm_waitqueue_signal() or rtdm_waitqueue_broadcast(), or
+ * flushed by a call to rtdm_waitqueue_flush().
+ *
+ * The waitqueue must have been locked by a call to
+ * rtdm_waitqueue_lock() prior to calling this service.
+ *
+ * @param wq locked waitqueue to wait on. The waitqueue lock is
+ * dropped when sleeping, then reacquired before this service returns
+ * to the caller.
+ *
+ * @return 0 on success, otherwise:
+ *
+ * - -EINTR is returned if the waitqueue has been flushed, or the
+ * calling task has received a Linux signal or has been forcibly
+ * unblocked by a call to rtdm_task_unblock().
+ */
+void rtdm_wait_locked(struct rtdm_wait_queue *wq);
+
+/**
+ * @fn void rtdm_waitqueue_lock(struct rtdm_wait_queue *wq, rtdm_lockctx_t 
context)
+ * @brief Lock a waitqueue
+ *
+ * Acquires the lock on the waitqueue @a wq.
+ *
+ * @param wq waitqueue to lock.
+ *
+ * @param context name of local variable to store the context in.
+ *
+ * @note Recursive locking might lead to unexpected behavior,
+ * including lock up.
+ */
+void rtdm_waitqueue_lock(struct rtdm_wait_queue *wq, rtdm_lockctx_t context);
+
+/**
+ * @fn void rtdm_waitqueue_unlock(struct rtdm_wait_queue *wq, rtdm_lockctx_t 
context)
+ * @brief Unlock a waitqueue
+ *
+ * Releases the lock on the waitqueue @a wq.
+ *
+ * @param wq waitqueue to unlock.
+ *
+ * @param context name of local variable to retrieve the context from.
+ */
+void rtdm_waitqueue_unlock(struct rtdm_wait_queue *wq, rtdm_lockctx_t context);
+
+/**
+ * @fn void rtdm_waitqueue_signal(struct rtdm_wait_queue *wq)
+ * @brief Signal a waitqueue
+ *
+ * Signals the waitqueue @a wq, waking up a single waiter (if
+ * any).
+ *
+ * @param wq waitqueue to signal.
+ *
+ * @return non-zero if a task has been readied as a result of this
+ * call, zero otherwise.
+ */
+void rtdm_waitqueue_signal(struct rtdm_wait_queue *wq);
+
+/**
+ * @fn void rtdm_waitqueue_broadcast(struct rtdm_wait_queue *wq)
+ * @brief Broadcast a waitqueue
+ *
+ * Broadcast the waitqueue @a wq, waking up all waiters. Each
+ * readied task may assume to have received the wake up event.
+ *
+ * @param wq waitqueue to broadcast.
+ *
+ * @return non-zero if at least one task has been readied as a result
+ * of this call, zero otherwise.
+ */
+void rtdm_waitqueue_broadcast(struct rtdm_wait_queue *wq);
+
+/**
+ * @fn void rtdm_waitqueue_flush(struct rtdm_wait_queue *wq)
+ * @brief Flush a waitqueue
+ *
+ * Flushes the waitqueue @a wq, unblocking all waiters with an error
+ * status (-EINTR).
+ *
+ * @param wq waitqueue to flush.
+ *
+ * @return non-zero if at least one task has been readied as a result
+ * of this call, zero otherwise.
+ */
+void rtdm_waitqueue_flush(struct rtdm_wait_queue *wq);
+
+/**
+ * @fn void rtdm_waitqueue_wakeup(struct rtdm_wait_queue *wq, rtdm_task_t 
waiter)
+ * @brief Signal a particular waiter on a waitqueue
+ *
+ * Signals the waitqueue @a wq, waking up waiter @a waiter only,
+ * which must be currently sleeping on the waitqueue.
+ *
+ * @param wq waitqueue to signal.
+ *
+ * @param waiter RTDM task to wake up.
+ */
+void rtdm_waitqueue_wakeup(struct rtdm_wait_queue *wq, rtdm_task_t waiter);
+
+/**
+ * @fn rtdm_for_each_waiter(rtdm_task_t pos, struct rtdm_wait_queue *wq)
+ * @brief Simple iterator for waitqueues
+ *
+ * This construct traverses the wait list of a given waitqueue
+ * @a wq, assigning each RTDM task pointer to the cursor variable
+ * @a pos, which must be of type rtdm_task_t.
+ *
+ * @a wq must have been locked by a call to rtdm_waitqueue_lock()
+ * prior to traversing its wait list.
+ *
+ * @param pos cursor variable holding a pointer to the RTDM task
+ * being fetched.
+ *
+ * @param wq waitqueue to scan.
+ *
+ * @note The waitqueue should not be signaled, broadcast or flushed
+ * during the traversal, unless the loop is aborted immediately
+ * after. Should multiple waiters be readied while iterating, the safe
+ * form rtdm_for_each_waiter_safe() must be used for traversal
+ * instead.
+ */
+rtdm_for_each_waiter(rtdm_task_t pos, struct rtdm_wait_queue *wq);
+
+/**
+ * @fn rtdm_for_each_waiter_safe(rtdm_task_t pos, rtdm_task_t tmp, struct 
rtdm_wait_queue *wq)
+ * @brief Safe iterator for waitqueues
+ *
+ * This construct traverses the wait list of a given waitqueue
+ * @a wq, assigning each RTDM task pointer to the cursor variable
+ * @a pos, which must be of type rtdm_task_t.
+ *
+ * Unlike with rtdm_for_each_waiter(), the waitqueue may be signaled,
+ * broadcast or flushed during the traversal.
+ *
+ * @a wq must have been locked by a call to rtdm_waitqueue_lock()
+ * prior to traversing its wait list.
+ *
+ * @param pos cursor variable holding a pointer to the RTDM task
+ * being fetched.
+ *
+ * @param tmp temporary cursor variable.
+ *
+ * @param wq waitqueue to scan.
+ */
+rtdm_for_each_waiter_safe(rtdm_task_t pos, rtdm_task_t tmp, struct 
rtdm_wait_queue *wq);
+
+/** @} in rtdm_sync */
+
+/** @} add rtdm_sync */
+
+/**
+ * @defgroup rtdm_foo Driver to driver services
+ * Inter-driver interface
+ *@{
+ */
+
+/**
  * @brief Open a device
  *
  * Refer to rt_dev_open() for parameters and return values
@@ -504,7 +908,7 @@ int rtdm_connect(int fd, const struct sockaddr *serv_addr, 
socklen_t addrlen);
 int rtdm_listen(int fd, int backlog);
 
 /**
- * @brief Accept a connection requests
+ * @brief Accept a connection request
  *
  * Refer to rt_dev_accept() for parameters and return values
  *
@@ -583,6 +987,8 @@ int rtdm_getsockname(int fd, struct sockaddr *name, 
socklen_t *namelen);
  */
 int rtdm_getpeername(int fd, struct sockaddr *name, socklen_t *namelen);
 
+/** @} Inter-driver calls */
+
 /** @} */
 
 /*!
diff --git a/kernel/cobalt/rtdm/device.c b/kernel/cobalt/rtdm/device.c
index 215e9d0..ef67495 100644
--- a/kernel/cobalt/rtdm/device.c
+++ b/kernel/cobalt/rtdm/device.c
@@ -29,7 +29,7 @@
 #include <trace/events/cobalt-rtdm.h>
 
 /**
- * @addtogroup rtdm_driver_api
+ * @addtogroup rtdm_driver_interface
  * @{
  */
 
@@ -132,7 +132,7 @@ struct rtdm_device *get_protocol_device(int 
protocol_family, int socket_type)
 }
 
 /**
- * @ingroup rtdm_driver_api
+ * @ingroup rtdm_driver_interface
  * @defgroup rtdm_device_register Device Registration Services
  * @{
  */
diff --git a/kernel/cobalt/rtdm/drvlib.c b/kernel/cobalt/rtdm/drvlib.c
index 209c4f5..cfc5127 100644
--- a/kernel/cobalt/rtdm/drvlib.c
+++ b/kernel/cobalt/rtdm/drvlib.c
@@ -35,7 +35,7 @@
 #include <trace/events/cobalt-rtdm.h>
 
 /**
- * @ingroup rtdm_driver_api
+ * @ingroup rtdm_driver_interface
  * @defgroup rtdm_clock Clock Services
  * @{
  */
@@ -97,7 +97,7 @@ nanosecs_abs_t rtdm_clock_read_monotonic(void);
 /** @} */
 
 /**
- * @ingroup rtdm_driver_api
+ * @ingroup rtdm_driver_interface
  * @defgroup rtdm_task Task Services
  * @{
  */
@@ -477,7 +477,7 @@ EXPORT_SYMBOL_GPL(rtdm_task_busy_sleep);
 /** @} */
 
 /**
- * @ingroup rtdm_driver_api
+ * @ingroup rtdm_driver_interface
  * @defgroup rtdm_timer Timer Services
  * @{
  */
@@ -669,7 +669,7 @@ void __rtdm_synch_flush(struct xnsynch *synch, unsigned 
long reason)
 EXPORT_SYMBOL_GPL(__rtdm_synch_flush);
 
 /**
- * @ingroup rtdm_driver_api
+ * @ingroup rtdm_driver_interface
  * @defgroup rtdm_sync Synchronisation Services
  * @{
  */
@@ -738,8 +738,9 @@ EXPORT_SYMBOL_GPL(rtdm_toseq_init);
 
 /** @} */
 
-/*!
- * @name Event Services
+/**
+ * @ingroup rtdm_sync
+ * @defgroup rtdm_sync_event Event Services
  * @{
  */
 
@@ -1089,8 +1090,9 @@ EXPORT_SYMBOL_GPL(rtdm_event_select_bind);
 
 /** @} */
 
-/*!
- * @name Semaphore Services
+/**
+ * @ingroup rtdm_sync
+ * @defgroup rtdm_sync_sem Semaphore Services
  * @{
  */
 
@@ -1368,8 +1370,9 @@ EXPORT_SYMBOL_GPL(rtdm_sem_select_bind);
 
 /** @} */
 
-/*!
- * @name Mutex Services
+/**
+ * @ingroup rtdm_sync
+ * @defgroup rtdm_sync_mutex Mutex services
  * @{
  */
 
@@ -1584,7 +1587,7 @@ EXPORT_SYMBOL_GPL(rtdm_mutex_timedlock);
 /** @} Synchronisation services */
 
 /**
- * @ingroup rtdm_driver_api
+ * @ingroup rtdm_driver_interface
  * @defgroup rtdm_irq Interrupt Management Services
  * @{
  */
@@ -1725,7 +1728,7 @@ int rtdm_irq_disable(rtdm_irq_t *irq_handle);
 #ifdef DOXYGEN_CPP /* Only used for doxygen doc generation */
 
 /**
- * @ingroup rtdm_driver_api
+ * @ingroup rtdm_driver_interface
  * @defgroup rtdm_nrtsignal Non-Real-Time Signalling Services
  *
  * These services provide a mechanism to request the execution of a specified
@@ -1800,7 +1803,7 @@ void rtdm_nrtsig_pend(rtdm_nrtsig_t *nrt_sig);
 #endif /* DOXYGEN_CPP */
 
 /**
- * @ingroup rtdm_driver_api
+ * @ingroup rtdm_driver_interface
  * @defgroup rtdm_util Utility Services
  * @{
  */


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

Reply via email to