From: Matthias Kruk <m@m10k.eu>
Date: Mon, 10 Feb 2020 11:48:40 +0000 (+0900)
Subject: klibc/sem: Add sem_peek() method and documentation for all semaphore functions
X-Git-Url: https://git.corax.cc/?a=commitdiff_plain;h=8d4d5e0cb09a7c167d453a24db3ccc088644e079;p=corax

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 87b39e5..acbe68e 100644
--- 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 97acbaa..955e64d 100644
--- 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);
+}