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