Browse code

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

Henning Westerholt authored on 23/06/2011 21:39:01
Showing 10 changed files
... ...
@@ -1,6 +1,4 @@
1 1
 /* 
2
- * $Id$
3
- * 
4 2
  * Copyright (C) 2006 iptelorg GmbH
5 3
  *
6 4
  * Permission to use, copy, modify, and distribute this software for any
... ...
@@ -12,18 +10,22 @@
12 12
  * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13 13
  * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 14
  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15
- * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15
+ * ACTION OF CONTRACT, NEGLIGENCEAtomic operations and memory barriers (alpha specific)
16 16
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 17
  */
18 18
 
19
-/** @file
20
- *  @brief atomic operations and memory barriers (alpha specific)
21
- *
22
- *  WARNING: atomic ops do not include memory barriers
23
- *  see atomic_ops.h for more details 
19
+/** 
20
+ * @file
21
+ * @brief Atomic operations and memory barriers (alpha specific)
24 22
  *
25
- *  Config defines:  - NOSMP 
26
- *                   - __CPU_alpha
23
+ * Atomic operations and memory barriers (alpha specific)
24
+ * \warning atomic ops do not include memory barriers, see atomic_ops.h
25
+ * for more details.
26
+ * 
27
+ * Config defines:
28
+ * - NOSMP 
29
+ * - __CPU_alpha
30
+ * @ingroup atomic
27 31
  */
28 32
 /* 
29 33
  * History:
... ...
@@ -1,6 +1,4 @@
1 1
 /* 
2
- * $Id$
3
- * 
4 2
  * Copyright (C) 2006 iptelorg GmbH
5 3
  *
6 4
  * Permission to use, copy, modify, and distribute this software for any
... ...
@@ -16,15 +14,20 @@
16 16
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 17
  */
18 18
 
19
-/** @file	@brief
20
- *  atomic ops and memory barriers for arm (>= v3)
21
- *  see atomic_ops.h for more details 
22
- *
23
- * Config defines: - NOSMP
24
- *                 - __CPU_arm
25
- *                 - __CPU_arm6    - armv6 support (supports atomic ops
26
- *                                    via ldrex/strex)
27
- */ 
19
+/**
20
+ * @file
21
+ * @brief Atomic ops and memory barriers for ARM (>= v3)
22
+ * 
23
+ * Atomic ops and memory barriers for ARM architecture (starting from version 3)
24
+ * see atomic_ops.h for more info.
25
+ * 
26
+ * Config defines:
27
+ * - NOSMP
28
+ * - __CPU_arm
29
+ * - __CPU_arm6    - armv6 support (supports atomic ops via ldrex/strex)
30
+ * @ingroup atomic
31
+ */
32
+
28 33
 /* 
29 34
  * History:
30 35
  * --------
... ...
@@ -1,6 +1,4 @@
1 1
 /* 
2
- * $Id$
3
- * 
4 2
  * Copyright (C) 2006 iptelorg GmbH
5 3
  *
6 4
  * Permission to use, copy, modify, and distribute this software for any
... ...
@@ -16,9 +14,22 @@
16 16
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 17
  */
18 18
 
19
-/** @file       @brief
20
- * common part for all the atomic operations (atomic_t and common operations)
21
- *  See @ref atomic_ops.h for more info.
19
+/**
20
+ * @defgroup atomic SIP-router atomic operations
21
+ * @brief  SIP-router atomic operations and memory barriers support
22
+ * 
23
+ * SIP-router atomic operations and memory barriers support for different CPU
24
+ * architectures implemented in assembler. It also provides some generic
25
+ * fallback code for architectures not currently supported.
26
+ */
27
+
28
+/**
29
+ * @file
30
+ * @brief Common part for all the atomic operations
31
+ * 
32
+ * Common part for all the atomic operations (atomic_t and common operations)
33
+ * see atomic_ops.h for more info.
34
+ * @ingroup atomic
22 35
  */
23 36
 
24 37
 /* 
... ...
@@ -27,18 +38,27 @@
27 27
  *  2006-03-08  created by andrei
28 28
  *  2007-05-13  split from atomic_ops.h (andrei)
29 29
  */
30
+
31
+
30 32
 #ifndef __atomic_common
31 33
 #define __atomic_common
32 34
 
33
-/** @brief atomic_t defined as a struct to easily catch non atomic ops. on it,
34
- * e.g.  atomic_t  foo; foo++  will generate a compile error */
35
+/**
36
+ * @brief atomic_t defined as a struct to easily catch non atomic operations on it.
37
+ * 
38
+ * atomic_t defined as a struct to easily catch non atomic operations on it,
39
+ * e.g. atomic_t foo; foo++  will generate a compile error.
40
+ */
35 41
 typedef struct{ volatile int val; } atomic_t; 
36 42
 
37 43
 
38
-/** @name AtomicOps store and load operations are atomic on all cpus, note however that they
44
+/** 
45
+ * @name Atomic load and store operations
46
+ * Atomic store and load operations are atomic on all cpus, note however that they
39 47
  * don't include memory barriers so if you want to use atomic_{get,set} 
40 48
  * to implement mutexes you must use the mb_* versions or explicitely use
41
- * the barriers */
49
+ * the barriers 
50
+ */
42 51
 
43 52
 /*@{ */
44 53
 
... ...
@@ -1,6 +1,4 @@
1 1
 /* 
2
- * $Id$
3
- * 
4 2
  * Copyright (C) 2006 iptelorg GmbH
5 3
  *
6 4
  * Permission to use, copy, modify, and distribute this software for any
... ...
@@ -16,20 +14,23 @@
16 16
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 17
  */
18 18
 
19
-/** @file @brief
20
- *  atomic operations and memory barriers (mips isa 2 and mips64 specific)
21
- *  WARNING: atomic ops do not include memory barriers
22
- *  see atomic_ops.h for more details 
23
- *  WARNING: not tested on mips64 (not even a compile test)
19
+/** 
20
+ * @file 
21
+ * @brief Atomic operations and memory barriers (MIPS isa 2 and MIPS64 specific)
22
+ * 
23
+ * Atomic operations and memory barriers (MIPS isa 2 and MIPS64 specific)
24
+ * \warning atomic ops do not include memory barriers, see atomic_ops.h for
25
+ * more details.
26
+ * \warning not tested on MIPS64 (not even a compile test)
24 27
  *
25
- *  Config defines:  - NOSMP (in NOSMP mode it will also work on mips isa 1
26
- *                            cpus that support LL and SC, see MIPS_HAS_LLSC
27
- *                            in atomic_ops.h)
28
- *                   - __CPU_MIPS64 (mips64 arch., in 64 bit mode: long and
29
- *                                    void* are 64 bits)
30
- *                   - __CPU_MIPS2 or __CPU_MIPS && MIPS_HAS_LLSC && NOSMP
31
- *                                 (if __CPU_MIPS64 is not defined)
28
+ * Config defines:
29
+ * - NOSMP (in NOSMP mode it will also work on mips isa 1 CPUs that support
30
+ *   LL and SC, see MIPS_HAS_LLSC in atomic_ops.h)
31
+ * - __CPU_MIPS64 (mips64 arch., in 64 bit mode: long and void* are 64 bits)
32
+ * - __CPU_MIPS2 or __CPU_MIPS && MIPS_HAS_LLSC && NOSMP (if __CPU_MIPS64 is not defined)
33
+ * @ingroup atomic
32 34
  */
35
+
33 36
 /* 
34 37
  * History:
35 38
  * --------
... ...
@@ -1,6 +1,4 @@
1 1
 /* 
2
- * $Id$
3
- * 
4 2
  * Copyright (C) 2006 iptelorg GmbH
5 3
  *
6 4
  * Permission to use, copy, modify, and distribute this software for any
... ...
@@ -16,32 +14,35 @@
16 16
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 17
  */
18 18
 
19
-/** @file @brief
20
- *  include file for native (asm) atomic operations and memory barriers
21
- *  WARNING: atomic ops do not include memory barriers
22
- *  See atomic_ops.h for more info.
23
- *  Expects atomic_t to be defined (#include "atomic_common.h")
19
+/**
20
+ * @file
21
+ * @brief Native (asm) atomic operations and memory barriers
22
+ * 
23
+ * Native (assembler) atomic operations and memory barriers.
24
+ * \warning atomic ops do not include memory barriers, see atomic_ops.h for
25
+ * more info. Expects atomic_t to be defined (#include "atomic_common.h")
24 26
  *
25
- * Config defines:   CC_GCC_LIKE_ASM  - the compiler support gcc style
26
- *                     inline asm
27
- *                   NOSMP - the code will be a little faster, but not SMP
28
- *                            safe
29
- *                   __CPU_i386, __CPU_x86_64, X86_OOSTORE - see 
30
- *                       atomic_x86.h
31
- *                   __CPU_mips, __CPU_mips2, __CPU_mips64, MIPS_HAS_LLSC - see
32
- *                       atomic_mip2.h
33
- *                   __CPU_ppc, __CPU_ppc64 - see atomic_ppc.h
34
- *                   __CPU_sparc - see atomic_sparc.h
35
- *                   __CPU_sparc64, SPARC64_MODE - see atomic_sparc64.h
36
- *                   __CPU_arm, __CPU_arm6 - see atomic_arm.h
37
- *                   __CPU_alpha - see atomic_alpha.h
27
+ * Config defines:   
28
+ * - CC_GCC_LIKE_ASM  - the compiler support gcc style inline asm
29
+ * - NOSMP - the code will be a little faster, but not SMP safe
30
+ * - __CPU_i386, __CPU_x86_64, X86_OOSTORE - see atomic_x86.h
31
+ * - __CPU_mips, __CPU_mips2, __CPU_mips64, MIPS_HAS_LLSC - see atomic_mip2.h
32
+ * - __CPU_ppc, __CPU_ppc64 - see atomic_ppc.h
33
+ * - __CPU_sparc - see atomic_sparc.h
34
+ * - __CPU_sparc64, SPARC64_MODE - see atomic_sparc64.h
35
+ * - __CPU_arm, __CPU_arm6 - see atomic_arm.h
36
+ * - __CPU_alpha - see atomic_alpha.h
37
+ * @ingroup atomic
38 38
  */
39
+
39 40
 /* 
40 41
  * History:
41 42
  * --------
42 43
  *  2006-03-08  created by andrei
43 44
  *  2007-05-13  split from atomic_ops.h (andrei)
44 45
  */
46
+
47
+
45 48
 #ifndef __atomic_native
46 49
 #define __atomic_native
47 50
 
... ...
@@ -1,6 +1,4 @@
1 1
 /* 
2
- * $Id$
3
- * 
4 2
  * Copyright (C) 2006 iptelorg GmbH
5 3
  *
6 4
  * Permission to use, copy, modify, and distribute this software for any
... ...
@@ -16,16 +14,22 @@
16 16
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 17
  */
18 18
 
19
-/** @file @brief
20
- *  atomic operations and memory barriers (powerpc and powerpc64 versions)
21
- *  WARNING: atomic ops do not include memory barriers
22
- *  see atomic_ops.h for more details 
23
- *  WARNING: not tested on ppc64
19
+/**
20
+ * @file
21
+ * @brief Atomic operations and memory barriers (PowerPC and PowerPC64 versions)
22
+ * 
23
+ * Atomic operations and memory barriers (PowerPC and PowerPC64 versions)
24
+ * \warning atomic ops do not include memory barriers see atomic_ops.h for
25
+ * more details. 
26
+ * \warning not tested on ppc64
24 27
  *
25
- *  Config defines:  - NOSMP
26
- *                   - __CPU_ppc64  (powerpc64 w/ 64 bits long and void*)
27
- *                   - __CPU_ppc    (powerpc or powerpc64 32bit mode)
28
+ * Config defines:
29
+ * - NOSMP
30
+ * - __CPU_ppc64  (powerpc64 w/ 64 bits long and void*)
31
+ * - __CPU_ppc    (powerpc or powerpc64 32bit mode)
32
+ * @ingroup atomic
28 33
  */
34
+
29 35
 /* 
30 36
  * History:
31 37
  * --------
... ...
@@ -39,6 +43,7 @@
39 39
  *                membar_*_atomic_setget (andrei)
40 40
  */
41 41
 
42
+
42 43
 #ifndef _atomic_ppc_h
43 44
 #define _atomic_ppc_h
44 45
 
... ...
@@ -1,6 +1,4 @@
1 1
 /* 
2
- * $Id$
3
- * 
4 2
  * Copyright (C) 2006 iptelorg GmbH
5 3
  *
6 4
  * Permission to use, copy, modify, and distribute this software for any
... ...
@@ -16,11 +14,16 @@
16 16
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 17
  */
18 18
 
19
-/** @file @brief
20
- *  memory barriers for sparc32 ( version < v 9))
21
- *  see atomic_ops.h for more details 
19
+/**
20
+ * @file
21
+ * @brief Memory barriers for SPARC32 ( version < v 9))
22
+ * 
23
+ * Memory barriers for SPARC32 ( version < v 9)), see atomic_ops.h for more
24
+ * details.
22 25
  *
23
- * Config defines: NOSMP
26
+ * Config defines: 
27
+ * - NOSMP
28
+ * @ingroup atomic
24 29
  */
25 30
 
26 31
 /* 
... ...
@@ -1,6 +1,4 @@
1 1
 /* 
2
- * $Id$
3
- * 
4 2
  * Copyright (C) 2006 iptelorg GmbH
5 3
  *
6 4
  * Permission to use, copy, modify, and distribute this software for any
... ...
@@ -16,15 +14,19 @@
16 16
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 17
  */
18 18
 
19
-/** @file @brief
20
- *  atomic operations and memory barriers (sparc64 version, 32 and 64 bit modes)
21
- *  WARNING: atomic ops do not include memory barriers
22
- *  see atomic_ops.h for more details 
19
+/**
20
+ * @file
21
+ * @brief Atomic operations and memory barriers (SPARC64 version, 32 and 64 bit modes)
22
+ * 
23
+ * Atomic operations and memory barriers (SPARC64 version, 32 and 64 bit modes)
24
+ * \warning atomic ops do not include memory barriers see atomic_ops.h for
25
+ * more details.
23 26
  *
24
- *  Config defs: - SPARC64_MODE (if defined long is assumed to be 64 bits
25
- *                               else long & void* are assumed to be 32 for
26
- *                               sparc32plus code)
27
- *               - NOSMP
27
+ * Config defines:
28
+ * - SPARC64_MODE (if defined long is assumed to be 64 bits else long & void*
29
+ *   are assumed to be 32 for SPARC32plus code)
30
+ * - NOSMP
31
+ * @ingroup atomic
28 32
  */
29 33
 
30 34
 /* 
... ...
@@ -1,6 +1,4 @@
1 1
 /* 
2
- * $Id$
3
- * 
4 2
  * Copyright (C) 2006 iptelorg GmbH
5 3
  *
6 4
  * Permission to use, copy, modify, and distribute this software for any
... ...
@@ -16,20 +14,24 @@
16 16
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 17
  */
18 18
 
19
-/** @file @brief
20
- *  atomic operations and memory barriers implemented using locks
21
- *  (for architectures not yet supported via inline asm)
19
+/**
20
+ * @file
21
+ * @brief Atomic operations and memory barriers implemented using locks
22 22
  *
23
- *  WARNING: atomic ops do not include memory barriers
24
- *  see atomic_ops.h for more details 
23
+ * Atomic operations and memory barriers implemented using locks
24
+ * (for architectures not yet supported via inline assembler).
25 25
  *
26
- *  Config defs: - NOSMP (membars are null in this case)
27
- *               - HAVE_ASM_INLINE_MEMBAR (membars arleady defined =>
28
- *                                          use them)
29
- *               - HAVE_ASM_INLINE_ATOMIC_OPS (atomic ops already defined
30
- *                                               => don't redefine them)
26
+ * \warning atomic ops do not include memory barriers, see atomic_ops.h
27
+ * for more details 
31 28
  *
29
+ * Config defines:
30
+ * - NOSMP (membars are null in this case)
31
+ * - HAVE_ASM_INLINE_MEMBAR (membars already defined => use them)
32
+ * - HAVE_ASM_INLINE_ATOMIC_OPS (atomic ops already defined => don't
33
+ *   redefine them)
34
+ * @ingroup atomic
32 35
  */
36
+
33 37
 /* 
34 38
  * History:
35 39
  * --------
... ...
@@ -40,6 +42,7 @@
40 40
  *                membar_*_atomic_setget (andrei)
41 41
  */
42 42
 
43
+
43 44
 #ifndef _atomic_unknown_h
44 45
 #define _atomic_unknown_h
45 46
 
... ...
@@ -1,6 +1,4 @@
1 1
 /* 
2
- * $Id$
3
- * 
4 2
  * Copyright (C) 2006 iptelorg GmbH
5 3
  *
6 4
  * Permission to use, copy, modify, and distribute this software for any
... ...
@@ -16,19 +14,22 @@
16 16
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 17
  */
18 18
 
19
-/** @file @brief
20
- *  atomic operations and memory barriers (x86 and x86_64/amd64 specific)
21
- *  WARNING: atomic ops do not include memory barriers
22
- *  see atomic_ops.h for more details 
19
+/**
20
+ * @file
21
+ * @brief Atomic operations and memory barriers (x86 and x86_64/amd64 specific)
22
+ * 
23
+ * Atomic operations and memory barriers (x86 and x86_64/amd64 specific)
24
+ * \warning atomic ops do not include memory barriers, see atomic_ops.h for more
25
+ * details.
23 26
  *
24
- *  Config defines:   - NOSMP
25
- *                    - X86_OOSTORE (out of order store, defined by default)
26
- *                    - X86_64_OOSTORE, like X86_OOSTORE, but for x86_64 cpus,
27
- *                      default off
28
- *                    - __CPU_x86_64 (64 bit mode, long and void* is 64 bit and
29
- *                                    the cpu has all of the mfence, lfence
30
- *                                    and sfence instructions)
31
- *                    - __CPU_i386  (486+, 32 bit)
27
+ * Config defines:
28
+ * - NOSMP
29
+ * - X86_OOSTORE (out of order store, defined by default)
30
+ * - X86_64_OOSTORE, like X86_OOSTORE, but for x86_64 CPUs, default off
31
+ * - __CPU_x86_64 (64 bit mode, long and void* is 64 bit and the CPU has all
32
+ *   of the mfence, lfence and sfence instructions)
33
+ * - __CPU_i386  (486+, 32 bit)
34
+ * @ingroup atomic
32 35
  */
33 36
 /* 
34 37
  * History: