[kernel] add some documentation
diff --git a/kernel/event.c b/kernel/event.c
index 97eb955..bdb6ec2 100644
--- a/kernel/event.c
+++ b/kernel/event.c
@@ -20,6 +20,26 @@
* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
+
+/**
+ * @file
+ * @brief Event wait and signal functions for threads.
+ * @defgroup event Events
+ *
+ * An event is a subclass of a wait queue.
+ *
+ * Threads wait for events, with optional timeouts.
+ *
+ * Events are "signaled", releasing waiting threads to continue.
+ * Signals may be one-shot signals (EVENT_FLAG_AUTOUNSIGNAL), in which
+ * case one signal releases only one thread, at which point it is
+ * automatically cleared. Otherwise, signals release all waiting threads
+ * to continue immediately until the signal is manually cleared with
+ * event_unsignal().
+ *
+ * @{
+ */
+
#include <debug.h>
#include <err.h>
#include <kernel/event.h>
@@ -28,6 +48,13 @@
#define EVENT_CHECK 1
#endif
+/**
+ * @brief Initialize an event object
+ *
+ * @param e Event object to initialize
+ * @param initial Initial value for "signaled" state
+ * @param flags 0 or EVENT_FLAG_AUTOUNSIGNAL
+ */
void event_init(event_t *e, bool initial, uint flags)
{
#if EVENT_CHECK
@@ -40,6 +67,15 @@
wait_queue_init(&e->wait);
}
+/**
+ * @brief Destroy an event object.
+ *
+ * Event's resources are freed and it may no longer be
+ * used until event_init() is called again. Any threads
+ * still waiting on the event will be resumed.
+ *
+ * @param e Event object to initialize
+ */
void event_destroy(event_t *e)
{
enter_critical_section();
@@ -56,6 +92,21 @@
exit_critical_section();
}
+/**
+ * @brief Wait for event to be signaled
+ *
+ * If the event has already been signaled, this function
+ * returns immediately. Otherwise, the current thread
+ * goes to sleep until the event object is signaled,
+ * the timeout is reached, or the event object is destroyed
+ * by another thread.
+ *
+ * @param e Event object
+ * @param timeout Timeout value, in ms
+ *
+ * @return 0 on success, ERR_TIMED_OUT on timeout,
+ * other values on other errors.
+ */
status_t event_wait_timeout(event_t *e, time_t timeout)
{
status_t ret = NO_ERROR;
@@ -85,11 +136,31 @@
return ret;
}
+/**
+ * @brief Same as event_wait_timeout(), but without a timeout.
+ */
status_t event_wait(event_t *e)
{
return event_wait_timeout(e, INFINITE_TIME);
}
+/**
+ * @brief Signal an event
+ *
+ * Signals an event. If EVENT_FLAG_AUTOUNSIGNAL is set in the event
+ * object's flags, only one waiting thread is allowed to proceed. Otherwise,
+ * all waiting threads are allowed to proceed until such time as
+ * event_unsignal() is called.
+ *
+ * @param e Event object
+ * @param reschedule If true, waiting thread(s) are executed immediately,
+ * and the current thread resumes only after the
+ * waiting threads have been satisfied. If false,
+ * waiting threads are placed at the end of the run
+ * queue.
+ *
+ * @return Returns NO_ERROR on success.
+ */
status_t event_signal(event_t *e, bool reschedule)
{
enter_critical_section();
@@ -121,6 +192,18 @@
return NO_ERROR;
}
+/**
+ * @brief Clear the "signaled" property of an event
+ *
+ * Used mainly for event objects without the EVENT_FLAG_AUTOUNSIGNAL
+ * flag. Once this function is called, threads that call event_wait()
+ * functions will once again need to wait until the event object
+ * is signaled.
+ *
+ * @param e Event object
+ *
+ * @return Returns NO_ERROR on success.
+ */
status_t event_unsignal(event_t *e)
{
enter_critical_section();