[PATCH] Immediate Values - Architecture Independent Code - kerneldoc

[Mathieu Desnoyers <mathieu.desnoyers@polymtl.ca>]

Immediate Values - Architecture Independent Code - kerneldoc

Add kerneldoc to Immediate Values API.

Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers@polymtl.ca>
CC: hch@infradead.org
---
 include/linux/immediate.h |   66 ++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 61 insertions(+), 5 deletions(-)

Index: linux-2.6-lttng/include/linux/immediate.h
===================================================================
--- linux-2.6-lttng.orig/include/linux/immediate.h	2007-07-14 20:27:40.000000000 -0400
+++ linux-2.6-lttng/include/linux/immediate.h	2007-07-14 20:40:40.000000000 -0400
@@ -19,18 +19,64 @@
 
 struct module;
 
+/**
+ * immediate_read - read immediate variable
+ * @var: pointer of type immediate_*_t
+ *
+ * Reads the value of @var.
+ */
 #define immediate_read(var)		_immediate_read(var)
+
+/**
+ * immediate_set - set immediate variable (with locking)
+ * @var: pointer of type immediate_*_t
+ * @i: required value
+ *
+ * Sets the value of @var, taking the module_mutex if required by
+ * the architecture.
+ */
 #define immediate_set(var, i)		((var)->value = (i))
+
+/**
+ * _immediate_set - set immediate variable (without locking)
+ * @var: pointer of type immediate_*_t
+ * @i: required value
+ *
+ * Sets the value of @var. Must be called with module_mutex held.
+ */
 #define _immediate_set(var, i)		immediate_set(var, i)
+
+/**
+ * immediate_set_early - set immediate variable at early boot
+ * @var: pointer of type immediate_*_t
+ * @i: required value
+ *
+ * Sets the value of @var. Should be used for early boot updates.
+ */
 #define immediate_set_early(var, i)	immediate_set(var, i)
+
+/**
+ * immediate_if - if () statement depending on an immediate value
+ * @var: pointer of type immediate_*_t
+ *
+ * Use as an if () statement depending on an immediate value.
+ */
 #define immediate_if(var)		if (immediate_read(var))
 
+/*
+ * Internal update functions.
+ */
 static inline void module_immediate_setup(struct module *mod) { }
 static inline void immediate_update_early(void) { }
 #endif
 
-/*
- * Always access this type with the provided functions.
+/**
+ * DEFINE_IMMEDIATE_TYPE - Define an immediate type
+ * @type: type that the immediate should hold
+ * @name: name of the immediate type
+ *
+ * Define new immediate types. Naming scheme is immediate_*_t.
+ * Always access these types with the provided functions.
  */
 #define DEFINE_IMMEDIATE_TYPE(type, name) \
 	typedef struct { type value; } name
@@ -44,18 +90,28 @@ DEFINE_IMMEDIATE_TYPE(int, immediate_int
 DEFINE_IMMEDIATE_TYPE(long, immediate_long_t);
 DEFINE_IMMEDIATE_TYPE(void*, immediate_void_ptr_t);
 
-/*
- * Use this macro to initialize an immediate value to an initial static value.
+/**
+ * IMMEDIATE_INIT - Static initialization of an immediate variable
+ * @i: required value
+ *
+ * Use this macro to initialize an immediate value to an initial static
+ * value.
  */
 #define IMMEDIATE_INIT(i)		{ (i) }
 
-/*
+/**
+ * _immediate_read - Read immediate value with standard memory load.
+ * @var: pointer of type immediate_*_t
+ *
  * Force a data read of the immediate value instead of the immediate value
  * based mechanism. Useful for __init and __exit section data read.
  */
 #define _immediate_read(var)		(var)->value
 
 /*
+ * _immediate_if - if () statement depending on immediate value (memory load)
+ * @var: pointer of type immediate_*_t
+ *
  * Force the use of a normal if () statement depending on an immediate value.
  */
 #define _immediate_if(var)		if (_immediate_read(var))
-- 
Mathieu Desnoyers
Computer Engineering Ph.D. Student, Ecole Polytechnique de Montreal
OpenPGP key fingerprint: 8CD5 52C3 8E3C 4140 715F  BA06 3F25 A8FE 3BAE 9A68