doxygen: convert existing docs to use proper doxygen structures and groups, small cleanups

atomic/atomic_alpha.h

@@ -1,6 +1,4 @@
 /* 
- * $Id$
- * 
  * Copyright (C) 2006 iptelorg GmbH
  *
  * Permission to use, copy, modify, and distribute this software for any
@@ -12,18 +10,22 @@
  * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
- * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ * ACTION OF CONTRACT, NEGLIGENCEAtomic operations and memory barriers (alpha specific)
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
 
-/** @file
- *  @brief atomic operations and memory barriers (alpha specific)
- *
- *  WARNING: atomic ops do not include memory barriers
- *  see atomic_ops.h for more details 
+/** 
+ * @file
+ * @brief Atomic operations and memory barriers (alpha specific)
  *
- *  Config defines:  - NOSMP 
- *                   - __CPU_alpha
+ * Atomic operations and memory barriers (alpha specific)
+ * \warning atomic ops do not include memory barriers, see atomic_ops.h
+ * for more details.
+ * 
+ * Config defines:
+ * - NOSMP 
+ * - __CPU_alpha
+ * @ingroup atomic
  */
 /* 
  * History:

atomic/atomic_arm.h

@@ -1,6 +1,4 @@
 /* 
- * $Id$
- * 
  * Copyright (C) 2006 iptelorg GmbH
  *
  * Permission to use, copy, modify, and distribute this software for any
@@ -16,15 +14,20 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
 
-/** @file	@brief
- *  atomic ops and memory barriers for arm (>= v3)
- *  see atomic_ops.h for more details 
- *
- * Config defines: - NOSMP
- *                 - __CPU_arm
- *                 - __CPU_arm6    - armv6 support (supports atomic ops
- *                                    via ldrex/strex)
- */ 
+/**
+ * @file
+ * @brief Atomic ops and memory barriers for ARM (>= v3)
+ * 
+ * Atomic ops and memory barriers for ARM architecture (starting from version 3)
+ * see atomic_ops.h for more info.
+ * 
+ * Config defines:
+ * - NOSMP
+ * - __CPU_arm
+ * - __CPU_arm6    - armv6 support (supports atomic ops via ldrex/strex)
+ * @ingroup atomic
+ */
+
 /* 
  * History:
  * --------

atomic/atomic_common.h

@@ -1,6 +1,4 @@
 /* 
- * $Id$
- * 
  * Copyright (C) 2006 iptelorg GmbH
  *
  * Permission to use, copy, modify, and distribute this software for any
@@ -16,9 +14,22 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
 
-/** @file       @brief
- * common part for all the atomic operations (atomic_t and common operations)
- *  See @ref atomic_ops.h for more info.
+/**
+ * @defgroup atomic SIP-router atomic operations
+ * @brief  SIP-router atomic operations and memory barriers support
+ * 
+ * SIP-router atomic operations and memory barriers support for different CPU
+ * architectures implemented in assembler. It also provides some generic
+ * fallback code for architectures not currently supported.
+ */
+
+/**
+ * @file
+ * @brief Common part for all the atomic operations
+ * 
+ * Common part for all the atomic operations (atomic_t and common operations)
+ * see atomic_ops.h for more info.
+ * @ingroup atomic
  */
 
 /* 
@@ -27,18 +38,27 @@
  *  2006-03-08  created by andrei
  *  2007-05-13  split from atomic_ops.h (andrei)
  */
+
+
 #ifndef __atomic_common
 #define __atomic_common
 
-/** @brief atomic_t defined as a struct to easily catch non atomic ops. on it,
- * e.g.  atomic_t  foo; foo++  will generate a compile error */
+/**
+ * @brief atomic_t defined as a struct to easily catch non atomic operations on it.
+ * 
+ * atomic_t defined as a struct to easily catch non atomic operations on it,
+ * e.g. atomic_t foo; foo++  will generate a compile error.
+ */
 typedef struct{ volatile int val; } atomic_t; 
 
 
-/** @name AtomicOps store and load operations are atomic on all cpus, note however that they
+/** 
+ * @name Atomic load and store operations
+ * Atomic store and load operations are atomic on all cpus, note however that they
  * don't include memory barriers so if you want to use atomic_{get,set} 
  * to implement mutexes you must use the mb_* versions or explicitely use
- * the barriers */
+ * the barriers 
+ */
 
 /*@{ */
 

atomic/atomic_mips2.h

@@ -1,6 +1,4 @@
 /* 
- * $Id$
- * 
  * Copyright (C) 2006 iptelorg GmbH
  *
  * Permission to use, copy, modify, and distribute this software for any
@@ -16,20 +14,23 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
 
-/** @file @brief
- *  atomic operations and memory barriers (mips isa 2 and mips64 specific)
- *  WARNING: atomic ops do not include memory barriers
- *  see atomic_ops.h for more details 
- *  WARNING: not tested on mips64 (not even a compile test)
+/** 
+ * @file 
+ * @brief Atomic operations and memory barriers (MIPS isa 2 and MIPS64 specific)
+ * 
+ * Atomic operations and memory barriers (MIPS isa 2 and MIPS64 specific)
+ * \warning atomic ops do not include memory barriers, see atomic_ops.h for
+ * more details.
+ * \warning not tested on MIPS64 (not even a compile test)
  *
- *  Config defines:  - NOSMP (in NOSMP mode it will also work on mips isa 1
- *                            cpus that support LL and SC, see MIPS_HAS_LLSC
- *                            in atomic_ops.h)
- *                   - __CPU_MIPS64 (mips64 arch., in 64 bit mode: long and
- *                                    void* are 64 bits)
- *                   - __CPU_MIPS2 or __CPU_MIPS && MIPS_HAS_LLSC && NOSMP
- *                                 (if __CPU_MIPS64 is not defined)
+ * Config defines:
+ * - NOSMP (in NOSMP mode it will also work on mips isa 1 CPUs that support
+ *   LL and SC, see MIPS_HAS_LLSC in atomic_ops.h)
+ * - __CPU_MIPS64 (mips64 arch., in 64 bit mode: long and void* are 64 bits)
+ * - __CPU_MIPS2 or __CPU_MIPS && MIPS_HAS_LLSC && NOSMP (if __CPU_MIPS64 is not defined)
+ * @ingroup atomic
  */
+
 /* 
  * History:
  * --------

atomic/atomic_native.h

@@ -1,6 +1,4 @@
 /* 
- * $Id$
- * 
  * Copyright (C) 2006 iptelorg GmbH
  *
  * Permission to use, copy, modify, and distribute this software for any
@@ -16,32 +14,35 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
 
-/** @file @brief
- *  include file for native (asm) atomic operations and memory barriers
- *  WARNING: atomic ops do not include memory barriers
- *  See atomic_ops.h for more info.
- *  Expects atomic_t to be defined (#include "atomic_common.h")
+/**
+ * @file
+ * @brief Native (asm) atomic operations and memory barriers
+ * 
+ * Native (assembler) atomic operations and memory barriers.
+ * \warning atomic ops do not include memory barriers, see atomic_ops.h for
+ * more info. Expects atomic_t to be defined (#include "atomic_common.h")
  *
- * Config defines:   CC_GCC_LIKE_ASM  - the compiler support gcc style
- *                     inline asm
- *                   NOSMP - the code will be a little faster, but not SMP
- *                            safe
- *                   __CPU_i386, __CPU_x86_64, X86_OOSTORE - see 
- *                       atomic_x86.h
- *                   __CPU_mips, __CPU_mips2, __CPU_mips64, MIPS_HAS_LLSC - see
- *                       atomic_mip2.h
- *                   __CPU_ppc, __CPU_ppc64 - see atomic_ppc.h
- *                   __CPU_sparc - see atomic_sparc.h
- *                   __CPU_sparc64, SPARC64_MODE - see atomic_sparc64.h
- *                   __CPU_arm, __CPU_arm6 - see atomic_arm.h
- *                   __CPU_alpha - see atomic_alpha.h
+ * Config defines:   
+ * - CC_GCC_LIKE_ASM  - the compiler support gcc style inline asm
+ * - NOSMP - the code will be a little faster, but not SMP safe
+ * - __CPU_i386, __CPU_x86_64, X86_OOSTORE - see atomic_x86.h
+ * - __CPU_mips, __CPU_mips2, __CPU_mips64, MIPS_HAS_LLSC - see atomic_mip2.h
+ * - __CPU_ppc, __CPU_ppc64 - see atomic_ppc.h
+ * - __CPU_sparc - see atomic_sparc.h
+ * - __CPU_sparc64, SPARC64_MODE - see atomic_sparc64.h
+ * - __CPU_arm, __CPU_arm6 - see atomic_arm.h
+ * - __CPU_alpha - see atomic_alpha.h
+ * @ingroup atomic
  */
+
 /* 
  * History:
  * --------
  *  2006-03-08  created by andrei
  *  2007-05-13  split from atomic_ops.h (andrei)
  */
+
+
 #ifndef __atomic_native
 #define __atomic_native
 

atomic/atomic_ppc.h

@@ -1,6 +1,4 @@
 /* 
- * $Id$
- * 
  * Copyright (C) 2006 iptelorg GmbH
  *
  * Permission to use, copy, modify, and distribute this software for any
@@ -16,16 +14,22 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
 
-/** @file @brief
- *  atomic operations and memory barriers (powerpc and powerpc64 versions)
- *  WARNING: atomic ops do not include memory barriers
- *  see atomic_ops.h for more details 
- *  WARNING: not tested on ppc64
+/**
+ * @file
+ * @brief Atomic operations and memory barriers (PowerPC and PowerPC64 versions)
+ * 
+ * Atomic operations and memory barriers (PowerPC and PowerPC64 versions)
+ * \warning atomic ops do not include memory barriers see atomic_ops.h for
+ * more details. 
+ * \warning not tested on ppc64
  *
- *  Config defines:  - NOSMP
- *                   - __CPU_ppc64  (powerpc64 w/ 64 bits long and void*)
- *                   - __CPU_ppc    (powerpc or powerpc64 32bit mode)
+ * Config defines:
+ * - NOSMP
+ * - __CPU_ppc64  (powerpc64 w/ 64 bits long and void*)
+ * - __CPU_ppc    (powerpc or powerpc64 32bit mode)
+ * @ingroup atomic
  */
+
 /* 
  * History:
  * --------
@@ -39,6 +43,7 @@
  *                membar_*_atomic_setget (andrei)
  */
 
+
 #ifndef _atomic_ppc_h
 #define _atomic_ppc_h
 

atomic/atomic_sparc.h

@@ -1,6 +1,4 @@
 /* 
- * $Id$
- * 
  * Copyright (C) 2006 iptelorg GmbH
  *
  * Permission to use, copy, modify, and distribute this software for any
@@ -16,11 +14,16 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
 
-/** @file @brief
- *  memory barriers for sparc32 ( version < v 9))
- *  see atomic_ops.h for more details 
+/**
+ * @file
+ * @brief Memory barriers for SPARC32 ( version < v 9))
+ * 
+ * Memory barriers for SPARC32 ( version < v 9)), see atomic_ops.h for more
+ * details.
  *
- * Config defines: NOSMP
+ * Config defines: 
+ * - NOSMP
+ * @ingroup atomic
  */
 
 /* 

atomic/atomic_sparc64.h

@@ -1,6 +1,4 @@
 /* 
- * $Id$
- * 
  * Copyright (C) 2006 iptelorg GmbH
  *
  * Permission to use, copy, modify, and distribute this software for any
@@ -16,15 +14,19 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
 
-/** @file @brief
- *  atomic operations and memory barriers (sparc64 version, 32 and 64 bit modes)
- *  WARNING: atomic ops do not include memory barriers
- *  see atomic_ops.h for more details 
+/**
+ * @file
+ * @brief Atomic operations and memory barriers (SPARC64 version, 32 and 64 bit modes)
+ * 
+ * Atomic operations and memory barriers (SPARC64 version, 32 and 64 bit modes)
+ * \warning atomic ops do not include memory barriers see atomic_ops.h for
+ * more details.
  *
- *  Config defs: - SPARC64_MODE (if defined long is assumed to be 64 bits
- *                               else long & void* are assumed to be 32 for
- *                               sparc32plus code)
- *               - NOSMP
+ * Config defines:
+ * - SPARC64_MODE (if defined long is assumed to be 64 bits else long & void*
+ *   are assumed to be 32 for SPARC32plus code)
+ * - NOSMP
+ * @ingroup atomic
  */
 
 /* 

atomic/atomic_unknown.h

@@ -1,6 +1,4 @@
 /* 
- * $Id$
- * 
  * Copyright (C) 2006 iptelorg GmbH
  *
  * Permission to use, copy, modify, and distribute this software for any
@@ -16,20 +14,24 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
 
-/** @file @brief
- *  atomic operations and memory barriers implemented using locks
- *  (for architectures not yet supported via inline asm)
+/**
+ * @file
+ * @brief Atomic operations and memory barriers implemented using locks
  *
- *  WARNING: atomic ops do not include memory barriers
- *  see atomic_ops.h for more details 
+ * Atomic operations and memory barriers implemented using locks
+ * (for architectures not yet supported via inline assembler).
  *
- *  Config defs: - NOSMP (membars are null in this case)
- *               - HAVE_ASM_INLINE_MEMBAR (membars arleady defined =>
- *                                          use them)
- *               - HAVE_ASM_INLINE_ATOMIC_OPS (atomic ops already defined
- *                                               => don't redefine them)
+ * \warning atomic ops do not include memory barriers, see atomic_ops.h
+ * for more details 
  *
+ * Config defines:
+ * - NOSMP (membars are null in this case)
+ * - HAVE_ASM_INLINE_MEMBAR (membars already defined => use them)
+ * - HAVE_ASM_INLINE_ATOMIC_OPS (atomic ops already defined => don't
+ *   redefine them)
+ * @ingroup atomic
  */
+
 /* 
  * History:
  * --------
@@ -40,6 +42,7 @@
  *                membar_*_atomic_setget (andrei)
  */
 
+
 #ifndef _atomic_unknown_h
 #define _atomic_unknown_h
 

atomic/atomic_x86.h

@@ -1,6 +1,4 @@
 /* 
- * $Id$
- * 
  * Copyright (C) 2006 iptelorg GmbH
  *
  * Permission to use, copy, modify, and distribute this software for any
@@ -16,19 +14,22 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
 
-/** @file @brief
- *  atomic operations and memory barriers (x86 and x86_64/amd64 specific)
- *  WARNING: atomic ops do not include memory barriers
- *  see atomic_ops.h for more details 
+/**
+ * @file
+ * @brief Atomic operations and memory barriers (x86 and x86_64/amd64 specific)
+ * 
+ * Atomic operations and memory barriers (x86 and x86_64/amd64 specific)
+ * \warning atomic ops do not include memory barriers, see atomic_ops.h for more
+ * details.
  *
- *  Config defines:   - NOSMP
- *                    - X86_OOSTORE (out of order store, defined by default)
- *                    - X86_64_OOSTORE, like X86_OOSTORE, but for x86_64 cpus,
- *                      default off
- *                    - __CPU_x86_64 (64 bit mode, long and void* is 64 bit and
- *                                    the cpu has all of the mfence, lfence
- *                                    and sfence instructions)
- *                    - __CPU_i386  (486+, 32 bit)
+ * Config defines:
+ * - NOSMP
+ * - X86_OOSTORE (out of order store, defined by default)
+ * - X86_64_OOSTORE, like X86_OOSTORE, but for x86_64 CPUs, default off
+ * - __CPU_x86_64 (64 bit mode, long and void* is 64 bit and the CPU has all
+ *   of the mfence, lfence and sfence instructions)
+ * - __CPU_i386  (486+, 32 bit)
+ * @ingroup atomic
  */
 /* 
  * History: