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
--
