Module: xenomai-forge
Branch: next
Commit: 372c4c5d3367aa6fe9320b37ecce30ab83edb603
URL:
http://git.xenomai.org/?p=xenomai-forge.git;a=commit;h=372c4c5d3367aa6fe9320b37ecce30ab83edb603
Author: Philippe Gerum <r...@xenomai.org>
Date: Sat Jun 14 19:24:25 2014 +0200
doc: overhaul of the doxygen-based contents - part 3
Mainly,
- Fixup TOC hierarchy grouping Cobalt-specific interfaces
- Fixup core tags for more clarity
- Update RTDM documentation in the wake of rtdm_fd introduction
---
doc/doxygen/manual-common.conf.in | 2 +-
include/cobalt/kernel/apc.h | 2 +-
include/cobalt/kernel/bufd.h | 2 +-
include/cobalt/kernel/clock.h | 2 +-
include/cobalt/kernel/heap.h | 2 +-
include/cobalt/kernel/intr.h | 2 +-
include/cobalt/kernel/lock.h | 2 +-
include/cobalt/kernel/map.h | 2 +-
include/cobalt/kernel/registry.h | 2 +-
include/cobalt/kernel/sched-idle.h | 2 +-
include/cobalt/kernel/sched-quota.h | 2 +-
include/cobalt/kernel/sched-rt.h | 2 +-
include/cobalt/kernel/sched-sporadic.h | 2 +-
include/cobalt/kernel/sched-tp.h | 2 +-
include/cobalt/kernel/sched-weak.h | 2 +-
include/cobalt/kernel/sched.h | 2 +-
include/cobalt/kernel/schedparam.h | 2 +-
include/cobalt/kernel/schedqueue.h | 2 +-
include/cobalt/kernel/select.h | 2 +-
include/cobalt/kernel/shadow.h | 2 +-
include/cobalt/kernel/stat.h | 4 +--
include/cobalt/kernel/synch.h | 2 +-
include/cobalt/kernel/thread.h | 2 +-
include/cobalt/kernel/timer.h | 2 +-
include/cobalt/kernel/vfile.h | 2 +-
include/cobalt/uapi/kernel/thread.h | 8 ++---
include/rtdm/rtdm.h | 2 +-
kernel/cobalt/apc.c | 4 +--
kernel/cobalt/arith.c | 4 +--
kernel/cobalt/bufd.c | 4 +--
kernel/cobalt/clock.c | 6 ++--
kernel/cobalt/debug.c | 4 +--
kernel/cobalt/heap.c | 4 +--
kernel/cobalt/init.c | 50 +++++++++++++++++-----------
kernel/cobalt/intr.c | 4 +--
kernel/cobalt/lock.c | 4 +--
kernel/cobalt/map.c | 4 +--
kernel/cobalt/registry.c | 4 +--
kernel/cobalt/rtdm/drvlib.c | 4 +--
kernel/cobalt/rtdm/fd.c | 49 ++++++++++++++++++++++++++-
kernel/cobalt/sched-quota.c | 2 +-
kernel/cobalt/sched.c | 6 ++--
kernel/cobalt/select.c | 4 +--
kernel/cobalt/shadow.c | 4 +--
kernel/cobalt/synch.c | 4 +--
kernel/cobalt/thread.c | 4 +--
kernel/cobalt/timer.c | 4 +--
kernel/cobalt/vfile.c | 4 +--
kernel/drivers/analogy/driver_facilities.c | 3 +-
lib/cobalt/clock.c | 4 +--
lib/cobalt/cond.c | 4 +--
lib/cobalt/init.c | 7 ++--
lib/cobalt/mq.c | 4 +--
lib/cobalt/mutex.c | 4 +--
lib/cobalt/semaphore.c | 4 +--
lib/cobalt/thread.c | 8 ++---
lib/cobalt/timer.c | 4 +--
57 files changed, 170 insertions(+), 111 deletions(-)
diff --git a/doc/doxygen/manual-common.conf.in
b/doc/doxygen/manual-common.conf.in
index 0911387..be13ba4 100644
--- a/doc/doxygen/manual-common.conf.in
+++ b/doc/doxygen/manual-common.conf.in
@@ -131,7 +131,7 @@ TAB_SIZE = 8
# You can put \n's in the value part of an alias to insert newlines.
ALIASES = \
- "coretags{1}=@par Tags\n@ref core-tags \"\1\"" \
+ "coretags{1}=@par Tags\n@ref cobalt-core-tags \"\1\""
\
"sideeffect=@par Side effects\n"
# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C
sources
diff --git a/include/cobalt/kernel/apc.h b/include/cobalt/kernel/apc.h
index c5f05ed..3cde7f3 100644
--- a/include/cobalt/kernel/apc.h
+++ b/include/cobalt/kernel/apc.h
@@ -23,7 +23,7 @@
#include <asm/xenomai/machine.h>
/**
- * @addtogroup core_apc
+ * @addtogroup cobalt_core_apc
* @{
*/
diff --git a/include/cobalt/kernel/bufd.h b/include/cobalt/kernel/bufd.h
index 6e57d26..92a4078 100644
--- a/include/cobalt/kernel/bufd.h
+++ b/include/cobalt/kernel/bufd.h
@@ -22,7 +22,7 @@
#include <linux/types.h>
/**
- * @addtogroup core_bufd
+ * @addtogroup cobalt_core_bufd
*
* @{
*/
diff --git a/include/cobalt/kernel/clock.h b/include/cobalt/kernel/clock.h
index 8686b68..5b74686 100644
--- a/include/cobalt/kernel/clock.h
+++ b/include/cobalt/kernel/clock.h
@@ -25,7 +25,7 @@
#include <cobalt/uapi/kernel/types.h>
/**
- * @addtogroup core_clock
+ * @addtogroup cobalt_core_clock
* @{
*/
diff --git a/include/cobalt/kernel/heap.h b/include/cobalt/kernel/heap.h
index 3d3836a..14221e6 100644
--- a/include/cobalt/kernel/heap.h
+++ b/include/cobalt/kernel/heap.h
@@ -27,7 +27,7 @@
#include <cobalt/uapi/kernel/heap.h>
/**
- * @addtogroup core_heap
+ * @addtogroup cobalt_core_heap
* @{
*
* @par Implementation constraints
diff --git a/include/cobalt/kernel/intr.h b/include/cobalt/kernel/intr.h
index 5e8716c..f1844e0 100644
--- a/include/cobalt/kernel/intr.h
+++ b/include/cobalt/kernel/intr.h
@@ -22,7 +22,7 @@
#include <cobalt/kernel/stat.h>
/**
- * @addtogroup core_irq
+ * @addtogroup cobalt_core_irq
* @{
*/
diff --git a/include/cobalt/kernel/lock.h b/include/cobalt/kernel/lock.h
index 8acbd14..d576c0a 100644
--- a/include/cobalt/kernel/lock.h
+++ b/include/cobalt/kernel/lock.h
@@ -25,7 +25,7 @@
#include <cobalt/kernel/assert.h>
/**
- * @addtogroup core_lock
+ * @addtogroup cobalt_core_lock
*
* @{
*/
diff --git a/include/cobalt/kernel/map.h b/include/cobalt/kernel/map.h
index 411a1d7..a402df5 100644
--- a/include/cobalt/kernel/map.h
+++ b/include/cobalt/kernel/map.h
@@ -22,7 +22,7 @@
#include <asm/bitsperlong.h>
/**
- * @addtogroup core_map
+ * @addtogroup cobalt_core_map
* @{
*/
diff --git a/include/cobalt/kernel/registry.h b/include/cobalt/kernel/registry.h
index 238a1ef..383754c 100644
--- a/include/cobalt/kernel/registry.h
+++ b/include/cobalt/kernel/registry.h
@@ -23,7 +23,7 @@
#include <cobalt/kernel/vfile.h>
/**
- * @addtogroup core_registry
+ * @addtogroup cobalt_core_registry
*
* @{
*/
diff --git a/include/cobalt/kernel/sched-idle.h
b/include/cobalt/kernel/sched-idle.h
index ec007cd..732ff84 100644
--- a/include/cobalt/kernel/sched-idle.h
+++ b/include/cobalt/kernel/sched-idle.h
@@ -24,7 +24,7 @@
#endif
/**
- * @addtogroup core_sched
+ * @addtogroup cobalt_core_sched
* @{
*/
diff --git a/include/cobalt/kernel/sched-quota.h
b/include/cobalt/kernel/sched-quota.h
index 3a70bc6..06b8f41 100644
--- a/include/cobalt/kernel/sched-quota.h
+++ b/include/cobalt/kernel/sched-quota.h
@@ -24,7 +24,7 @@
#endif
/**
- * @addtogroup core_sched
+ * @addtogroup cobalt_core_sched
* @{
*/
diff --git a/include/cobalt/kernel/sched-rt.h b/include/cobalt/kernel/sched-rt.h
index 5108a7a..ffb7223 100644
--- a/include/cobalt/kernel/sched-rt.h
+++ b/include/cobalt/kernel/sched-rt.h
@@ -24,7 +24,7 @@
#endif
/**
- * @addtogroup core_sched
+ * @addtogroup cobalt_core_sched
* @{
*/
diff --git a/include/cobalt/kernel/sched-sporadic.h
b/include/cobalt/kernel/sched-sporadic.h
index 6a647cf..a6aac77 100644
--- a/include/cobalt/kernel/sched-sporadic.h
+++ b/include/cobalt/kernel/sched-sporadic.h
@@ -24,7 +24,7 @@
#endif
/**
- * @addtogroup core_sched
+ * @addtogroup cobalt_core_sched
* @{
*/
diff --git a/include/cobalt/kernel/sched-tp.h b/include/cobalt/kernel/sched-tp.h
index e15a067..6ae5ff8 100644
--- a/include/cobalt/kernel/sched-tp.h
+++ b/include/cobalt/kernel/sched-tp.h
@@ -24,7 +24,7 @@
#endif
/**
- * @addtogroup core_sched
+ * @addtogroup cobalt_core_sched
* @{
*/
diff --git a/include/cobalt/kernel/sched-weak.h
b/include/cobalt/kernel/sched-weak.h
index 948fcaf..400aa73 100644
--- a/include/cobalt/kernel/sched-weak.h
+++ b/include/cobalt/kernel/sched-weak.h
@@ -24,7 +24,7 @@
#endif
/**
- * @addtogroup core_sched
+ * @addtogroup cobalt_core_sched
* @{
*/
diff --git a/include/cobalt/kernel/sched.h b/include/cobalt/kernel/sched.h
index 566d2d8..c04c553 100644
--- a/include/cobalt/kernel/sched.h
+++ b/include/cobalt/kernel/sched.h
@@ -31,7 +31,7 @@
#include <asm/xenomai/machine.h>
/**
- * @addtogroup core_sched
+ * @addtogroup cobalt_core_sched
* @{
*/
diff --git a/include/cobalt/kernel/schedparam.h
b/include/cobalt/kernel/schedparam.h
index cd51a2f..1fe9c31 100644
--- a/include/cobalt/kernel/schedparam.h
+++ b/include/cobalt/kernel/schedparam.h
@@ -20,7 +20,7 @@
#define _COBALT_KERNEL_SCHEDPARAM_H
/**
- * @addtogroup core_sched
+ * @addtogroup cobalt_core_sched
* @{
*/
diff --git a/include/cobalt/kernel/schedqueue.h
b/include/cobalt/kernel/schedqueue.h
index 0e0d4e4..f7e87a3 100644
--- a/include/cobalt/kernel/schedqueue.h
+++ b/include/cobalt/kernel/schedqueue.h
@@ -22,7 +22,7 @@
#include <cobalt/kernel/list.h>
/**
- * @addtogroup core_sched
+ * @addtogroup cobalt_core_sched
* @{
*/
diff --git a/include/cobalt/kernel/select.h b/include/cobalt/kernel/select.h
index d1951bd..1bac45a 100644
--- a/include/cobalt/kernel/select.h
+++ b/include/cobalt/kernel/select.h
@@ -23,7 +23,7 @@
#include <cobalt/kernel/thread.h>
/**
- * @addtogroup core_select
+ * @addtogroup cobalt_core_select
* @{
*/
diff --git a/include/cobalt/kernel/shadow.h b/include/cobalt/kernel/shadow.h
index 3b3e378..69f972e 100644
--- a/include/cobalt/kernel/shadow.h
+++ b/include/cobalt/kernel/shadow.h
@@ -26,7 +26,7 @@
#include <cobalt/uapi/signal.h>
/**
- * @addtogroup core_shadow
+ * @addtogroup cobalt_core_shadow
* @{
*/
struct xnthread;
diff --git a/include/cobalt/kernel/stat.h b/include/cobalt/kernel/stat.h
index f633a90..713ade4 100644
--- a/include/cobalt/kernel/stat.h
+++ b/include/cobalt/kernel/stat.h
@@ -23,8 +23,8 @@
#include <cobalt/kernel/clock.h>
/*
- * @ingroup core_thread
- * @defgroup core_stat Thread runtime statistics
+ * @ingroup cobalt_core_thread
+ * @defgroup cobalt_core_stat Thread runtime statistics
* @{
*/
#ifdef CONFIG_XENO_OPT_STATS
diff --git a/include/cobalt/kernel/synch.h b/include/cobalt/kernel/synch.h
index cdcf6d1..b6f6380 100644
--- a/include/cobalt/kernel/synch.h
+++ b/include/cobalt/kernel/synch.h
@@ -25,7 +25,7 @@
#include <cobalt/uapi/kernel/synch.h>
/**
- * @addtogroup core_synch
+ * @addtogroup cobalt_core_synch
* @{
*/
#define XNSYNCH_CLAIMED 0x10 /* Claimed by other thread(s) w/ PIP */
diff --git a/include/cobalt/kernel/thread.h b/include/cobalt/kernel/thread.h
index 48e51aa..3b9bcc7 100644
--- a/include/cobalt/kernel/thread.h
+++ b/include/cobalt/kernel/thread.h
@@ -34,7 +34,7 @@
#include <asm/xenomai/thread.h>
/**
- * @addtogroup core_thread
+ * @addtogroup cobalt_core_thread
* @{
*/
#define XNTHREAD_BLOCK_BITS
(XNSUSP|XNPEND|XNDELAY|XNDORMANT|XNRELAX|XNMIGRATE|XNHELD)
diff --git a/include/cobalt/kernel/timer.h b/include/cobalt/kernel/timer.h
index c85eebe..9f8c959 100644
--- a/include/cobalt/kernel/timer.h
+++ b/include/cobalt/kernel/timer.h
@@ -25,7 +25,7 @@
#include <cobalt/kernel/list.h>
/**
- * @addtogroup core_timer
+ * @addtogroup cobalt_core_timer
* @{
*/
#define XN_INFINITE ((xnticks_t)0)
diff --git a/include/cobalt/kernel/vfile.h b/include/cobalt/kernel/vfile.h
index dc52b59..8618600 100644
--- a/include/cobalt/kernel/vfile.h
+++ b/include/cobalt/kernel/vfile.h
@@ -26,7 +26,7 @@
#include <cobalt/kernel/lock.h>
/**
- * @addtogroup core_vfile
+ * @addtogroup cobalt_core_vfile
* @{
*/
diff --git a/include/cobalt/uapi/kernel/thread.h
b/include/cobalt/uapi/kernel/thread.h
index b77a0c7..be6ac0e 100644
--- a/include/cobalt/uapi/kernel/thread.h
+++ b/include/cobalt/uapi/kernel/thread.h
@@ -21,8 +21,8 @@
#include <cobalt/uapi/kernel/types.h>
/**
- * @ingroup core_thread
- * @defgroup core_thread_states Thread state flags
+ * @ingroup cobalt_core_thread
+ * @defgroup cobalt_core_thread_states Thread state flags
* @brief Bits reporting permanent or transient states of threads
* @{
*/
@@ -55,8 +55,8 @@
/** @} */
/**
- * @ingroup core_thread
- * @defgroup core_thread_info Thread information flags
+ * @ingroup cobalt_core_thread
+ * @defgroup cobalt_core_thread_info Thread information flags
* @brief Bits reporting events notified to threads
* @{
*/
diff --git a/include/rtdm/rtdm.h b/include/rtdm/rtdm.h
index 3933a7e..a6c1e49 100644
--- a/include/rtdm/rtdm.h
+++ b/include/rtdm/rtdm.h
@@ -30,7 +30,7 @@
#include <boilerplate/wrappers.h>
/**
- * @defgroup rtdm Real-Time Driver Model
+ * @defgroup rtdm RTDM
*
* The Real-Time Driver Model (RTDM) provides a unified interface to
* both users and developers of real-time device
diff --git a/kernel/cobalt/apc.c b/kernel/cobalt/apc.c
index 14972f3..0956dbc 100644
--- a/kernel/cobalt/apc.c
+++ b/kernel/cobalt/apc.c
@@ -21,8 +21,8 @@
#include <cobalt/kernel/apc.h>
/**
- * @ingroup core
- * @defgroup core_apc Asynchronous Procedure Calls
+ * @ingroup cobalt_core
+ * @defgroup cobalt_core_apc Asynchronous Procedure Calls
*
* Services for scheduling function calls in the Linux domain
*
diff --git a/kernel/cobalt/arith.c b/kernel/cobalt/arith.c
index a5a1955..5603c2d 100644
--- a/kernel/cobalt/arith.c
+++ b/kernel/cobalt/arith.c
@@ -19,8 +19,8 @@
#include <linux/module.h>
/**
- * @ingroup core
- * @defgroup core_arith In-kernel arithmetics
+ * @ingroup cobalt_core
+ * @defgroup cobalt_core_arith In-kernel arithmetics
*
* A collection of helpers performing arithmetics not implicitly
* available from kernel context via GCC helpers. Many of these
diff --git a/kernel/cobalt/bufd.c b/kernel/cobalt/bufd.c
index cde8f53..f6f0f4f 100644
--- a/kernel/cobalt/bufd.c
+++ b/kernel/cobalt/bufd.c
@@ -23,8 +23,8 @@
#include <asm/xenomai/syscall.h>
/**
- * @ingroup core
- * @defgroup core_bufd Buffer descriptor
+ * @ingroup cobalt_core
+ * @defgroup cobalt_core_bufd Buffer descriptor
*
* Abstraction for copying data to/from different address spaces
*
diff --git a/kernel/cobalt/clock.c b/kernel/cobalt/clock.c
index f8136b7..a578f89 100644
--- a/kernel/cobalt/clock.c
+++ b/kernel/cobalt/clock.c
@@ -27,8 +27,8 @@
#include <asm/xenomai/calibration.h>
#include <trace/events/cobalt-core.h>
/**
- * @ingroup core
- * @defgroup core_clock Clock services
+ * @ingroup cobalt_core
+ * @defgroup cobalt_core_clock Clock services
*
* @{
*/
@@ -544,7 +544,7 @@ EXPORT_SYMBOL_GPL(xnclock_deregister);
*
* @param clock The clock for which a new event was received.
*
- * @coretags{isr-only, atomic-entry}
+ * @coretags{coreirq-only, atomic-entry}
*
* @note The current CPU must be part of the real-time affinity set,
* otherwise weird things may happen.
diff --git a/kernel/cobalt/debug.c b/kernel/cobalt/debug.c
index 02ff586..8a0c436 100644
--- a/kernel/cobalt/debug.c
+++ b/kernel/cobalt/debug.c
@@ -28,8 +28,8 @@
#include "debug.h"
/**
- * @ingroup core
- * @defgroup core_debug Debugging services
+ * @ingroup cobalt_core
+ * @defgroup cobalt_core_debug Debugging services
* @{
*/
struct xnvfile_directory debug_vfroot;
diff --git a/kernel/cobalt/heap.c b/kernel/cobalt/heap.c
index 47fadc8..1ea12af 100644
--- a/kernel/cobalt/heap.c
+++ b/kernel/cobalt/heap.c
@@ -36,8 +36,8 @@
#include <cobalt/kernel/assert.h>
/**
- * @ingroup core
- * @defgroup core_heap Dynamic memory allocation services
+ * @ingroup cobalt_core
+ * @defgroup cobalt_core_heap Dynamic memory allocation services
*
* The implementation of the memory allocator follows the algorithm
* described in a USENIX 1988 paper called "Design of a General
diff --git a/kernel/cobalt/init.c b/kernel/cobalt/init.c
index d701e58..5e84f27 100644
--- a/kernel/cobalt/init.c
+++ b/kernel/cobalt/init.c
@@ -36,14 +36,17 @@
#include "procfs.h"
/**
- * @defgroup core Xenomai nucleus
+ * @defgroup cobalt Cobalt
*
- * The Xenomai nucleus supplements the native Linux kernel in dual
- * kernel configurations. It deals with all time-critical activities,
- * such as handling interrupts, and scheduling real-time threads. The
- * nucleus has higher priority over all the native kernel activities.
+ * Cobalt supplements the native Linux kernel in dual kernel
+ * configurations. It deals with all time-critical activities, such as
+ * handling interrupts, and scheduling real-time threads. The Cobalt
+ * kernel has higher priority over all the native kernel activities.
+ *
+ * Cobalt provides an implementation of the POSIX and RTDM interfaces
+ * based on a set of generic RTOS building blocks.
*/
-MODULE_DESCRIPTION("Xenomai nucleus");
+MODULE_DESCRIPTION("Cobalt kernel");
MODULE_AUTHOR("r...@xenomai.org");
MODULE_LICENSE("GPL");
@@ -468,14 +471,19 @@ fail:
device_initcall(xenomai_init);
/**
- * @ingroup core
- * @page dual-kernel-core-tags Dual kernel service tags
- * @anchor core-tags
+ * @ingroup cobalt
+ * @defgroup cobalt_core Cobalt kernel
+ *
+ * The Cobalt kernel implements generic RTOS building blocks.
+ *
+ * @{
*
- * Xenomai core services in dual kernel configuration may be
- * restricted to particular calling contexts, or entail specific
- * side-effects. To describe this information, each service documented
- * by this manual bears a set of tags when applicable.
+ * @page cobalt-core-tags Dual kernel service tags
+ *
+ * Cobalt kernel services may be restricted to particular calling
+ * contexts, or entail specific side-effects. To describe this
+ * information, each service documented by this manual 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.
@@ -484,20 +492,22 @@ device_initcall(xenomai_init);
* <b>Context tags</b>
* <TABLE>
* <TR><TH>Tag</TH> <TH>Context on entry</TH></TR>
- * <TR><TD>secondary-only</TD> <TD>Must be called from a regular Linux
task</TD></TR>
- * <TR><TD>primary-only</TD> <TD>Must be called from a hard real-time
task</TD></TR>
- * <TR><TD>isr-only</TD> <TD>Must be called from a hard real-time IRQ
handler</TD></TR>
+ * <TR><TD>primary-only</TD> <TD>Must be called from a Cobalt task in
primary mode</TD></TR>
+ * <TR><TD>coreirq-only</TD> <TD>Must be called from a Cobalt IRQ
handler</TD></TR>
+ * <TR><TD>secondary-only</TD> <TD>Must be called from a Cobalt task in
secondary mode or regular Linux task</TD></TR>
* <TR><TD>rtdm-task</TD> <TD>Must be called from a RTDM driver
task</TD></TR>
- * <TR><TD>mode-unrestricted</TD> <TD>Must be called from a Xenomai task
context in either primary or secondary mode</TD></TR>
- * <TR><TD>task-unrestricted</TD> <TD>May be called from a regular Linux
or Xenomai task context indifferently</TD></TR>
+ * <TR><TD>mode-unrestricted</TD> <TD>Must be called from a Cobalt task
in either primary or secondary mode</TD></TR>
+ * <TR><TD>task-unrestricted</TD> <TD>May be called from a Cobalt or
regular Linux task indifferently</TD></TR>
* <TR><TD>unrestricted</TD> <TD>May be called from any context previously
described</TD></TR>
- * <TR><TD>atomic-entry</TD> <TD>Caller must currently hold the Xenomai
nucleus big lock</TD></TR>
+ * <TR><TD>atomic-entry</TD> <TD>Caller must currently hold the big Cobalt
kernel lock (nklock)</TD></TR>
* </TABLE>
*
* @par
* <b>Possible side-effects</b>
* <TABLE>
* <TR><TH>Tag</TH> <TH>Description</TH></TR>
- * <TR><TD>might-switch</TD> <TD>A thread context switch may happen in the
Xenomai core</TD></TR>
+ * <TR><TD>might-switch</TD> <TD>The Cobalt kernel may switch
context</TD></TR>
* </TABLE>
+ *
+ * @}
*/
diff --git a/kernel/cobalt/intr.c b/kernel/cobalt/intr.c
index 19ddbc9..9b76b09 100644
--- a/kernel/cobalt/intr.c
+++ b/kernel/cobalt/intr.c
@@ -29,8 +29,8 @@
#include <trace/events/cobalt-core.h>
/**
- * @ingroup core
- * @defgroup core_irq Interrupt management
+ * @ingroup cobalt_core
+ * @defgroup cobalt_core_irq Interrupt management
* @{
*/
#define XNINTR_MAX_UNHANDLED 1000
diff --git a/kernel/cobalt/lock.c b/kernel/cobalt/lock.c
index eea99ff..24df298 100644
--- a/kernel/cobalt/lock.c
+++ b/kernel/cobalt/lock.c
@@ -21,8 +21,8 @@
#include <cobalt/kernel/lock.h>
/**
- * @ingroup core
- * @defgroup core_lock Locking services
+ * @ingroup cobalt_core
+ * @defgroup cobalt_core_lock Locking services
*
* The Xenomai core deals with concurrent activities from two distinct
* kernels running side-by-side. When interrupts are involved, the
diff --git a/kernel/cobalt/map.c b/kernel/cobalt/map.c
index 9783c28..161d24c 100644
--- a/kernel/cobalt/map.c
+++ b/kernel/cobalt/map.c
@@ -22,8 +22,8 @@
#include <asm/xenomai/machine.h>
/**
- * @ingroup core
- * @defgroup core_map Lightweight key-to-object mapping service
+ * @ingroup cobalt_core
+ * @defgroup cobalt_core_map Lightweight key-to-object mapping service
*
* A map is a simple indexing structure which associates unique
* integer keys with pointers to objects. The current implementation
diff --git a/kernel/cobalt/registry.c b/kernel/cobalt/registry.c
index c5f2b74..7713e2e 100644
--- a/kernel/cobalt/registry.c
+++ b/kernel/cobalt/registry.c
@@ -25,8 +25,8 @@
#include <cobalt/kernel/assert.h>
/**
- * @ingroup core
- * @defgroup core_registry Registry services
+ * @ingroup cobalt_core
+ * @defgroup cobalt_core_registry Registry services
*
* The registry provides a mean to index object descriptors on unique
* alphanumeric keys. When labeled this way, an object is globally
diff --git a/kernel/cobalt/rtdm/drvlib.c b/kernel/cobalt/rtdm/drvlib.c
index 138b3ab..d39fefe 100644
--- a/kernel/cobalt/rtdm/drvlib.c
+++ b/kernel/cobalt/rtdm/drvlib.c
@@ -478,7 +478,7 @@ EXPORT_SYMBOL_GPL(rtdm_timer_stop);
* - -ETIMEDOUT is returned if @c expiry describes an absolute date in the
* past.
*
- * @coretags{isr-only}
+ * @coretags{coreirq-only}
*/
int rtdm_timer_start_in_handler(rtdm_timer_t *timer, nanosecs_abs_t expiry,
nanosecs_rel_t interval,
@@ -489,7 +489,7 @@ int rtdm_timer_start_in_handler(rtdm_timer_t *timer,
nanosecs_abs_t expiry,
*
* @param[in,out] timer Timer handle as returned by rtdm_timer_init()
*
- * @coretags{isr-only}
+ * @coretags{coreirq-only}
*/
void rtdm_timer_stop_in_handler(rtdm_timer_t *timer);
#endif /* DOXYGEN_CPP */
diff --git a/kernel/cobalt/rtdm/fd.c b/kernel/cobalt/rtdm/fd.c
index 1d640f1..4ac2d60 100644
--- a/kernel/cobalt/rtdm/fd.c
+++ b/kernel/cobalt/rtdm/fd.c
@@ -167,6 +167,19 @@ int rtdm_fd_enter(struct xnsys_ppd *p, struct rtdm_fd *fd,
int ufd,
return err;
}
+/**
+ * @brief Retrieve and lock a RTDM file descriptor
+ *
+ * @param[in] ufd User-side file descriptor
+ *
+ * @return Pointer to the RTDM file descriptor matching @a ufd, or
+ * ERR_PTR(-EBADF).
+ *
+ * @note The file descriptor returned must be later released by a call
+ * to rtdm_fd_put().
+ *
+ * @coretags{unrestricted}
+ */
struct rtdm_fd *rtdm_fd_get(struct xnsys_ppd *p, int ufd, unsigned int magic)
{
struct rtdm_fd *res;
@@ -262,6 +275,16 @@ static void rtdm_fd_put_inner(struct rtdm_fd *fd, spl_t s)
}
}
+/**
+ * @brief Release a RTDM file descriptor obtained via rtdm_fd_get()
+ *
+ * @param[in] fd RTDM file descriptor to release
+ *
+ * @note Every call to rtdm_fd_get() must be matched by a call to
+ * rtdm_fd_put().
+ *
+ * @coretags{unrestricted}
+ */
void rtdm_fd_put(struct rtdm_fd *fd)
{
spl_t s;
@@ -271,6 +294,20 @@ void rtdm_fd_put(struct rtdm_fd *fd)
}
EXPORT_SYMBOL_GPL(rtdm_fd_put);
+/**
+ * @brief Hold a reference on a RTDM file descriptor
+ *
+ * @param[in] fd Target file descriptor
+ *
+ * @note rtdm_fd_lock() increments the reference counter of @a fd. You
+ * only need to call this function in special scenarios, e.g. when
+ * keeping additional references to the file descriptor that have
+ * different lifetimes. Only use rtdm_fd_lock() on descriptors that
+ * are currently locked via an earlier rtdm_fd_get()/rtdm_fd_lock() or
+ * while running a device operation handler.
+ *
+ * @coretags{unrestricted}
+ */
int rtdm_fd_lock(struct rtdm_fd *fd)
{
spl_t s;
@@ -287,12 +324,22 @@ int rtdm_fd_lock(struct rtdm_fd *fd)
}
EXPORT_SYMBOL_GPL(rtdm_fd_lock);
+/**
+ * @brief Drop a reference on a RTDM file descriptor
+ *
+ * @param[in] fd Target file descriptor
+ *
+ * @note Every call to rtdm_fd_lock() must be matched by a call to
+ * rtdm_fd_unlock().
+ *
+ * @coretags{unrestricted}
+ */
void rtdm_fd_unlock(struct rtdm_fd *fd)
{
spl_t s;
xnlock_get_irqsave(&__rtdm_fd_lock, s);
-/* just warn if context was a dangling pointer */
+ /* Warn if fd was unreferenced. */
XENO_ASSERT(NUCLEUS, fd->refs > 0);
rtdm_fd_put_inner(fd, s);
}
diff --git a/kernel/cobalt/sched-quota.c b/kernel/cobalt/sched-quota.c
index 6842b71..9891a3c 100644
--- a/kernel/cobalt/sched-quota.c
+++ b/kernel/cobalt/sched-quota.c
@@ -471,7 +471,7 @@ static void xnsched_quota_migrate(struct xnthread *thread,
struct xnsched *sched
}
/**
- * @ingroup core_sched
+ * @ingroup cobalt_core_sched
* @defgroup sched_quota SCHED_QUOTA scheduling policy
*
* The SCHED_QUOTA policy enforces a limitation on the CPU consumption
diff --git a/kernel/cobalt/sched.c b/kernel/cobalt/sched.c
index c77f591..a3791a1 100644
--- a/kernel/cobalt/sched.c
+++ b/kernel/cobalt/sched.c
@@ -28,8 +28,8 @@
#include <trace/events/cobalt-core.h>
/**
- * @ingroup core
- * @defgroup core_sched Thread scheduling control
+ * @ingroup cobalt_core
+ * @defgroup cobalt_core_sched Thread scheduling control
* @{
*/
@@ -100,7 +100,7 @@ MODULE_PARM_DESC(watchdog_timeout, "Watchdog timeout (s)");
* software lockups. It kills any offending thread which is found to
* monopolize the CPU so as to starve the Linux kernel for too long.
*
- * @coretags{isr-only, atomic-entry}
+ * @coretags{coreirq-only, atomic-entry}
*/
static void watchdog_handler(struct xntimer *timer)
{
diff --git a/kernel/cobalt/select.c b/kernel/cobalt/select.c
index b09b7c3..417aca9 100644
--- a/kernel/cobalt/select.c
+++ b/kernel/cobalt/select.c
@@ -26,8 +26,8 @@
#include <cobalt/kernel/apc.h>
/**
- * @ingroup core
- * @defgroup core_select Synchronous I/O multiplexing
+ * @ingroup cobalt_core
+ * @defgroup cobalt_core_select Synchronous I/O multiplexing
*
* This module implements the services needed for implementing the
* POSIX select() service, or any other event multiplexing services.
diff --git a/kernel/cobalt/shadow.c b/kernel/cobalt/shadow.c
index 9b9d089..b6d54bf 100644
--- a/kernel/cobalt/shadow.c
+++ b/kernel/cobalt/shadow.c
@@ -61,8 +61,8 @@
#include "debug.h"
/**
- * @ingroup core
- * @defgroup core_shadow Real-time shadow services
+ * @ingroup cobalt_core
+ * @defgroup cobalt_core_shadow Real-time shadow services
*
* Real-time shadow services.
*
diff --git a/kernel/cobalt/synch.c b/kernel/cobalt/synch.c
index ffc9e4b..82d2262 100644
--- a/kernel/cobalt/synch.c
+++ b/kernel/cobalt/synch.c
@@ -25,8 +25,8 @@
#include <trace/events/cobalt-core.h>
/**
- * @ingroup core
- * @defgroup core_synch Thread synchronization services
+ * @ingroup cobalt_core
+ * @defgroup cobalt_core_synch Thread synchronization services
* @{
*/
diff --git a/kernel/cobalt/thread.c b/kernel/cobalt/thread.c
index 62566c1..f4e665e 100644
--- a/kernel/cobalt/thread.c
+++ b/kernel/cobalt/thread.c
@@ -39,8 +39,8 @@
#include <trace/events/cobalt-core.h>
/**
- * @ingroup core
- * @defgroup core_thread Thread services
+ * @ingroup cobalt_core
+ * @defgroup cobalt_core_thread Thread services
* @{
*/
diff --git a/kernel/cobalt/timer.c b/kernel/cobalt/timer.c
index d1e42bf..18ae873 100644
--- a/kernel/cobalt/timer.c
+++ b/kernel/cobalt/timer.c
@@ -30,8 +30,8 @@
#include <trace/events/cobalt-core.h>
/**
- * @ingroup core
- * @defgroup core_timer Timer services
+ * @ingroup cobalt_core
+ * @defgroup cobalt_core_timer Timer services
*
* The Xenomai timer facility depends on a clock source (xnclock) for
* scheduling the next activation times.
diff --git a/kernel/cobalt/vfile.c b/kernel/cobalt/vfile.c
index 0878025..416eb0a 100644
--- a/kernel/cobalt/vfile.c
+++ b/kernel/cobalt/vfile.c
@@ -26,8 +26,8 @@
#include <asm/xenomai/wrappers.h>
/**
- * @ingroup core
- * @defgroup core_vfile Virtual file services
+ * @ingroup cobalt_core
+ * @defgroup cobalt_core_vfile Virtual file services
*
* Virtual files provide a mean to export Xenomai object states to
* user-space, based on common kernel interfaces. This encapsulation
diff --git a/kernel/drivers/analogy/driver_facilities.c
b/kernel/drivers/analogy/driver_facilities.c
index 3e69615..7d2d883 100644
--- a/kernel/drivers/analogy/driver_facilities.c
+++ b/kernel/drivers/analogy/driver_facilities.c
@@ -23,7 +23,8 @@
#include <rtdm/analogy/device.h>
/**
- * @defgroup analogy Analogy interface
+ * @ingroup cobalt
+ * @defgroup analogy Analogy framework
* A RTDM-based interface for implementing DAQ card drivers
*/
diff --git a/lib/cobalt/clock.c b/lib/cobalt/clock.c
index 6ab387a..843084a 100644
--- a/lib/cobalt/clock.c
+++ b/lib/cobalt/clock.c
@@ -32,8 +32,8 @@
#include "internal.h"
/**
- * @ingroup cobalt
- * @defgroup cobalt_time Clocks and timers
+ * @ingroup cobalt_api
+ * @defgroup cobalt_api_time Clocks and timers
*
* Cobalt/POSIX clock and timer services
*
diff --git a/lib/cobalt/cond.c b/lib/cobalt/cond.c
index 2f2399b..4388872 100644
--- a/lib/cobalt/cond.c
+++ b/lib/cobalt/cond.c
@@ -22,8 +22,8 @@
#include "internal.h"
/**
- * @ingroup cobalt
- * @defgroup cobalt_cond Condition variables
+ * @ingroup cobalt_api
+ * @defgroup cobalt_api_cond Condition variables
*
* Cobalt/POSIX condition variable services
*
diff --git a/lib/cobalt/init.c b/lib/cobalt/init.c
index ac19e56..c33e9b2 100644
--- a/lib/cobalt/init.c
+++ b/lib/cobalt/init.c
@@ -36,11 +36,12 @@
#include "init.h"
/**
- * @defgroup cobalt Cobalt/POSIX real-time API
+ * @ingroup cobalt
+ * @defgroup cobalt_api POSIX interface
*
- * The Cobalt interface is an implementation of a small subset of the
+ * The Cobalt/POSIX interface is an implementation of a subset of the
* <a href="http://www.opengroup.org/onlinepubs/000095399/functions/";>
- * Single Unix specification</a> over the Xenomai generic RTOS core.
+ * Single Unix specification</a> over the Cobalt core.
*/
__attribute__ ((weak))
diff --git a/lib/cobalt/mq.c b/lib/cobalt/mq.c
index 147b588..0b0dfbd 100644
--- a/lib/cobalt/mq.c
+++ b/lib/cobalt/mq.c
@@ -26,8 +26,8 @@
#include "internal.h"
/**
- * @ingroup cobalt
- * @defgroup cobalt_mq Message queues
+ * @ingroup cobalt_api
+ * @defgroup cobalt_api_mq Message queues
*
* Cobalt/POSIX message queue services
*
diff --git a/lib/cobalt/mutex.c b/lib/cobalt/mutex.c
index 3be2cb6..73c25e7 100644
--- a/lib/cobalt/mutex.c
+++ b/lib/cobalt/mutex.c
@@ -23,8 +23,8 @@
#include "internal.h"
/**
- * @ingroup cobalt
- * @defgroup cobalt_mutex Mutual exclusion
+ * @ingroup cobalt_api
+ * @defgroup cobalt_api_mutex Mutual exclusion
*
* Cobalt/POSIX mutual exclusion services
*
diff --git a/lib/cobalt/semaphore.c b/lib/cobalt/semaphore.c
index efadc4c..a29881c 100644
--- a/lib/cobalt/semaphore.c
+++ b/lib/cobalt/semaphore.c
@@ -27,8 +27,8 @@
#include "internal.h"
/**
- * @ingroup cobalt
- * @defgroup cobalt_sem Semaphores
+ * @ingroup cobalt_api
+ * @defgroup cobalt_api_sem Semaphores
*
* Cobalt/POSIX semaphore services
*
diff --git a/lib/cobalt/thread.c b/lib/cobalt/thread.c
index 2f3f793..0fbb433 100644
--- a/lib/cobalt/thread.c
+++ b/lib/cobalt/thread.c
@@ -31,8 +31,8 @@
#include <boilerplate/ancillaries.h>
/**
- * @ingroup cobalt
- * @defgroup cobalt_thread Thread management
+ * @ingroup cobalt_api
+ * @defgroup cobalt_api_thread Thread management
*
* Cobalt/POSIX thread management services
*
@@ -688,8 +688,8 @@ COBALT_IMPL(int, pthread_join, (pthread_t thread, void
**retval))
/** @} */
/**
- * @ingroup cobalt
- * @defgroup cobalt_sched Scheduling management
+ * @ingroup cobalt_api
+ * @defgroup cobalt_api_sched Scheduling management
*
* Cobalt/POSIX scheduling management services
* @{
diff --git a/lib/cobalt/timer.c b/lib/cobalt/timer.c
index 9023b71..634c639 100644
--- a/lib/cobalt/timer.c
+++ b/lib/cobalt/timer.c
@@ -21,7 +21,7 @@
#include "internal.h"
/**
- * @addtogroup cobalt_time
+ * @addtogroup cobalt_api_time
* @{
*/
@@ -174,7 +174,7 @@ COBALT_IMPL(int, timer_settime, (timer_t timerid,
* (member @a it_value) and reload value (member @a it_interval) of
* the timer @a timerid. The values are returned as time intervals,
* and as multiples of the system clock tick duration (see note in
- * section @ref cobalt_time "Clocks and timers services" for details
+ * section @ref cobalt_api_time "Clocks and timers services" for details
* on the duration of the system clock tick). If the timer was not
* started, the returned members @a it_value and @a it_interval of @a
* value are zero.
_______________________________________________
Xenomai-git mailing list
Xenomai-git@xenomai.org
http://www.xenomai.org/mailman/listinfo/xenomai-git
