klibc/sem: Add sem_peek() method and documentation for all semaphore functions

diff --git a/kernel/include/sem.h b/kernel/include/sem.h
index 87b39e5996cf0c71c9807400b8d8855936b1c7d6..acbe68ed153411b50d3339b0c6e3fc1574b24841 100644 (file)
--- a/kernel/include/sem.h
+++ b/kernel/include/sem.h
@@ -11,8 +11,79 @@ typedef struct {
        task_t     *sem_waitq[CONFIG_SEM_WAITQLEN];
 } sem_t;
 
+/*
+ * sem_wait() - Decrease a semaphore, waiting if necessary
+ *
+ * SYNOPSIS
+ *  int sem_wait(sem_t *sem);
+ *
+ * DESCRIPTION
+ *  The sem_wait() decreases the value of the semaphore pointed
+ *  to by `sem'. If the semaphore cannot be immediately decreased,
+ *  the calling task will be suspended and added to the semaphore's
+ *  wait list. Once the semaphore gets increased by another task,
+ *  all tasks waiting on the semaphore will be woken up, and the
+ *  order in which the tasks will get to pass the semaphore depends
+ *  on the scheduler.
+ *  If sem_wait() cannot immediately increase the semaphore, it will
+ *  keep trying until it succeeds, meaning that the calling task may
+ *  be suspended indefinitely if no other task invokes sem_post() on
+ *  the same semaphore.
+ *
+ * RETURN VALUE
+ *  0 the value of the semaphore has been successfully decreased
+ */
 int sem_wait(sem_t*);
+
+/*
+ * sem_trywait() - Decrease a semaphore
+ *
+ * SYNOPSIS
+ *  int sem_trywait(sem_t *sem);
+ *
+ * DESCRIPTION
+ *  The sem_trywait() function will attempt to decrease the value of
+ *  the semaphore pointed to by `sem'. If the semaphore cannot be
+ *  decreased immediately, the function will return an error.
+ *
+ * RETURN VALUE
+ *        0 The value of the semaphore has been successfully decreased
+ *  -EAGAIN The semaphore could not immediately be decreased
+ */
 int sem_trywait(sem_t*);
+
+/*
+ * sem_post() - Increase a semaphore
+ *
+ * SYNOPSIS
+ *  int sem_post(sem_t *sem);
+ *
+ * DESCRIPTION
+ *  The sem_post() function will increase the value of the semaphore
+ *  pointed to by `sem'. If the operation succeeds, sem_post() will
+ *  also cause all tasks that are waiting on the semaphore to be woken
+ *  up. On failure, the state of the semaphore remains unchanged.
+ *
+ * RETURN VALUE
+ *           0 The semaphore's value has been successfully increased
+ *  -EOVERFLOW The operation would have caused an overflow
+ */
 int sem_post(sem_t*);
 
+/*
+ * sem_peek() - Get the value of a semaphore
+ *
+ * SYNOPSIS
+ *  int sem_peek(sem_t *sem);
+ *
+ * DESCRIPTION
+ *  The sem_peek() function will obtain the value of semaphore pointed
+ *  to by `sem' and return its value. The value returned will always be
+ *  larger or equal to zero.
+ *
+ * RETURN VALUE
+ *  * The current value of the semaphore (>= 0)
+ */
+int sem_peek(sem_t*);
+
 #endif /* __SEM_H */

diff --git a/kernel/klibc/sem.c b/kernel/klibc/sem.c
index 97acbaa08d6a49c20ae4637fad24a41df6eee976..955e64d694af8623612d92b54990271bd0f24a92 100644 (file)
--- a/kernel/klibc/sem.c
+++ b/kernel/klibc/sem.c
@@ -121,3 +121,16 @@ int sem_post(sem_t *sem)
 
        return(ret_val);
 }
+
+int sem_peek(sem_t *sem)
+{
+       int ret_val;
+
+       spinlock_lock(&(sem->sem_lock));
+
+       ret_val = sem->sem_count;
+
+       spinlock_unlock(&(sem->sem_lock));
+
+       return(ret_val);
+}