[PATCH] Immediate Values - PowerPC Optimization - kerneldoc

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

Immediate Values - PowerPC Optimization - kerneldoc

Add kerneldoc to Immediate Values (PowerPC Optimization) API.

Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers@polymtl.ca>
CC: hch@infradead.org
---
 include/asm-powerpc/immediate.h |   51 ++++++++++++++++++++++++++++------------
 1 file changed, 36 insertions(+), 15 deletions(-)

Index: linux-2.6-lttng/include/asm-powerpc/immediate.h
===================================================================
--- linux-2.6-lttng.orig/include/asm-powerpc/immediate.h	2007-07-14 20:54:47.000000000 -0400
+++ linux-2.6-lttng/include/asm-powerpc/immediate.h	2007-07-14 20:56:50.000000000 -0400
@@ -24,14 +24,18 @@ struct __immediate {
 	long size;		/* Type size. */
 };
 
-/*
+/**
+ * immediate_read - read immediate variable
+ * @var: pointer of type immediate_*_t
+ *
+ * Reads the value of @var.
  * Optimized version of the immediate.
- * Make sure the 2 bytes update will be atomic by aligning the immediate
- * value.
- * Use a normal memory read for the 4 bytes immediate because there is no way to
- * atomically update it without using a seqlock read side, which would cost more
- * in term of total i-cache and d-cache space than a simple memory read.
  * Do not use in __init and __exit functions. Use _immediate_read() instead.
+ * Makes sure the 2 bytes update will be atomic by aligning the immediate
+ * value. Use a normal memory read for the 4 bytes immediate because there is no
+ * way to atomically update it without using a seqlock read side, which would
+ * cost more in term of total i-cache and d-cache space than a simple memory
+ * read.
  */
 #define immediate_read(var)						\
 	({								\
@@ -65,37 +69,54 @@ struct __immediate {
 		value;							\
 	})
 
-/*
- * Update immediate value, can take module mutex.
+/**
+ * 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_update(1);
 
-/*
- * Update immediate value. Module mutex must already be taken.
+/**
+ * _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) \
 	(var)->value = (i); \
 	immediate_update(0);
 
-/*
- * Update immediate value at early boot.
+/**
+ * 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) \
 	(var)->value = (i); \
 	immediate_update_early();
 
-/*
+/**
+ * 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.
+ * Do not use in __init and __exit functions. Use _immediate_if() instead.
  * Branch depending on an immediate value. Could eventually be optimized further
  * by improving gcc to give the ability to patch a jump instruction instead of
  * the value it depends on.
- * Do not use in __init and __exit functions. Use _immediate_if() instead.
  */
 #define immediate_if(var)	if (unlikely(immediate_read(var)))
 
 /*
- * Used internally.
+ * Internal update functions.
  */
 extern void immediate_update(int lock);
 extern void module_immediate_setup(struct module *mod);
-- 
Mathieu Desnoyers
Computer Engineering Ph.D. Student, Ecole Polytechnique de Montreal
OpenPGP key fingerprint: 8CD5 52C3 8E3C 4140 715F  BA06 3F25 A8FE 3BAE 9A68