Re: Updated generic semaphore patch set

[Harvey Harrison <harvey.harrison@gmail.com>]

From: Harvey Harrison <harvey.harrison@gmail.com>
Subject: [PATCH] semaphore: add stubs for kerneldoc to semphore functions

The difference between down/down_trylock/down_interruptable/down_killable
should be expanded to note the difference/use case, a simple stub is added here.

Signed-off-by: Harvey Harrison <harvey.harrison@gmail.com>
---
This applies on top of the last patch I sent, feel free to just use it as
a base for a fuller version.

 kernel/semaphore.c |   37 ++++++++++++++++++++++++++++++++++---
 1 files changed, 34 insertions(+), 3 deletions(-)

diff --git a/kernel/semaphore.c b/kernel/semaphore.c
index bae1017..f48ac5e 100644
--- a/kernel/semaphore.c
+++ b/kernel/semaphore.c
@@ -98,6 +98,12 @@ static noinline void __sched __up(struct semaphore *sem)
 	wake_up_process(waiter->task);
 }
 
+/**
+ * down - acquire the semaphore
+ * @sem: the semaphore to be acquired
+ *
+ * This can be called from interrupt context, unlike mutexes.
+ */
 void down(struct semaphore *sem)
 {
 	unsigned long flags;
@@ -111,6 +117,12 @@ void down(struct semaphore *sem)
 }
 EXPORT_SYMBOL(down);
 
+/**
+ * down_killable - try to acquire the semaphore
+ * @sem: the semaphore to be acquired
+ *
+ * This can be called from interrupt context, unlike mutexes.
+ */
 int down_interruptible(struct semaphore *sem)
 {
 	unsigned long flags;
@@ -127,6 +139,12 @@ int down_interruptible(struct semaphore *sem)
 }
 EXPORT_SYMBOL(down_interruptible);
 
+/**
+ * down_killable - try to acquire the semaphore
+ * @sem: the semaphore to be acquired
+ *
+ * This can be called from interrupt context, unlike mutexes.
+ */
 int down_killable(struct semaphore *sem)
 {
 	unsigned long flags;
@@ -147,7 +165,7 @@ EXPORT_SYMBOL(down_killable);
  * down_trylock - try to acquire the semaphore, without waiting
  * @sem: the semaphore to be acquired
  *
- * Try to acquire the semaphore atomically.  Returns 0 if the mutex has
+ * Try to acquire the semaphore atomically.  Returns 0 if the semaphore has
  * been acquired successfully and 1 if it is contended.
  *
  * NOTE: This return value is inverted from both spin_trylock and
@@ -171,7 +189,14 @@ int down_trylock(struct semaphore *sem)
 }
 EXPORT_SYMBOL(down_trylock);
 
-int down_timeout(struct semaphore *sem, long jiffies)
+/**
+ * down_timeout - try to acquire the semaphore within a timeout
+ * @sem: the semaphore to be acquired
+ * @timeout: the length to wait before timing out, in jiffies
+ *
+ * This can be called from interrupt context, unlike mutexes.
+ */
+int down_timeout(struct semaphore *sem, long timeout)
 {
 	unsigned long flags;
 	int result = 0;
@@ -180,13 +205,19 @@ int down_timeout(struct semaphore *sem, long jiffies)
 	if (likely(sem->count > 0))
 		sem->count--;
 	else
-		result = __down_timeout(sem, jiffies);
+		result = __down_timeout(sem, timeout);
 	spin_unlock_irqrestore(&sem->lock, flags);
 
 	return result;
 }
 EXPORT_SYMBOL(down_timeout);
 
+/**
+ * up - release the semaphore
+ * @sem: the semaphore to be released
+ *
+ * This can be called from interrupt context, unlike mutexes.
+ */
 void up(struct semaphore *sem)
 {
 	unsigned long flags;
-- 
1.5.4.4.684.g0e08