[kernel] add some documentation
diff --git a/kernel/thread.c b/kernel/thread.c
index 860e712..58dff8d 100644
--- a/kernel/thread.c
+++ b/kernel/thread.c
@@ -20,6 +20,16 @@
* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
+
+/**
+ * @file
+ * @brief Kernel threading
+ *
+ * This file is the core kernel threading interface.
+ *
+ * @defgroup thread Threads
+ * @{
+ */
#include <debug.h>
#include <list.h>
#include <malloc.h>
@@ -100,6 +110,33 @@
strlcpy(t->name, name, sizeof(t->name));
}
+/**
+ * @brief Create a new thread
+ *
+ * This function creates a new thread. The thread is initially suspended, so you
+ * need to call thread_resume() to execute it.
+ *
+ * @param name Name of thread
+ * @param entry Entry point of thread
+ * @param arg Arbitrary argument passed to entry()
+ * @param priority Execution priority for the thread.
+ * @param stack_size Stack size for the thread.
+ *
+ * Thread priority is an integer from 0 (lowest) to 31 (highest). Some standard
+ * prioritys are defined in <kernel/thread.h>:
+ *
+ * HIGHEST_PRIORITY
+ * DPC_PRIORITY
+ * HIGH_PRIORITY
+ * DEFAULT_PRIORITY
+ * LOW_PRIORITY
+ * IDLE_PRIORITY
+ * LOWEST_PRIORITY
+ *
+ * Stack size is typically set to DEFAULT_STACK_SIZE
+ *
+ * @return Pointer to thread object, or NULL on failure.
+ */
thread_t *thread_create(const char *name, thread_start_routine entry, void *arg, int priority, size_t stack_size)
{
thread_t *t;
@@ -143,6 +180,16 @@
return t;
}
+/**
+ * @brief Make a suspended thread executable.
+ *
+ * This function is typically called to start a thread which has just been
+ * created with thread_create()
+ *
+ * @param t Thread to resume
+ *
+ * @return NO_ERROR on success, ERR_NOT_SUSPENDED if thread was not suspended.
+ */
status_t thread_resume(thread_t *t)
{
#if THREAD_CHECKS
@@ -186,6 +233,13 @@
free(t);
}
+/**
+ * @brief Terminate the current thread
+ *
+ * Current thread exits with the specified return code.
+ *
+ * This function does not return.
+ */
void thread_exit(int retcode)
{
#if THREAD_CHECKS
@@ -216,10 +270,15 @@
arch_idle();
}
-/*
+/**
+ * @brief Cause another thread to be executed.
+ *
* Internal reschedule routine. The current thread needs to already be in whatever
* state and queues it needs to be in. This routine simply picks the next thread and
* switches to it.
+ *
+ * This is probably not the function you're looking for. See
+ * thread_yield() instead.
*/
void thread_resched(void)
{
@@ -317,6 +376,15 @@
arch_context_switch(oldthread, newthread);
}
+/**
+ * @brief Yield the cpu to another thread
+ *
+ * This function places the current thread at the end of the run queue
+ * and yields the cpu to another waiting thread (if any.)
+ *
+ * This function will return at some later time. Possibly immediately if
+ * no other threads are waiting to execute.
+ */
void thread_yield(void)
{
#if THREAD_CHECKS
@@ -339,6 +407,21 @@
exit_critical_section();
}
+/**
+ * @brief Briefly yield cpu to another thread
+ *
+ * This function is similar to thread_yield(), except that it will
+ * restart more quickly.
+ *
+ * This function places the current thread at the head of the run
+ * queue and then yields the cpu to another thread.
+ *
+ * Exception: If the time slice for this thread has expired, then
+ * the thread goes to the end of the run queue.
+ *
+ * This function will return at some later time. Possibly immediately if
+ * no other threads are waiting to execute.
+ */
void thread_preempt(void)
{
#if THREAD_CHECKS
@@ -364,6 +447,16 @@
exit_critical_section();
}
+/**
+ * @brief Suspend thread until woken.
+ *
+ * This function schedules another thread to execute. This function does not
+ * return until the thread is made runable again by some other module.
+ *
+ * You probably don't want to call this function directly; it's meant to be called
+ * from other modules, such as mutex, which will presumably set the thread's
+ * state to blocked and add it to some queue or another.
+ */
void thread_block(void)
{
#if THREAD_CHECKS
@@ -407,7 +500,16 @@
return INT_RESCHEDULE;
}
-/* Put thread to sleep; delay specified in ms */
+/**
+ * @brief Put thread to sleep; delay specified in ms
+ *
+ * This function puts the current thread to sleep until the specified
+ * delay in ms has expired.
+ *
+ * Note that this function could sleep for longer than the specified delay if
+ * other threads are running. When the timer expires, this thread will
+ * be placed at the head of the run queue.
+ */
void thread_sleep(time_t delay)
{
timer_t timer;
@@ -426,6 +528,11 @@
exit_critical_section();
}
+/**
+ * @brief Initialize threading system
+ *
+ * This function is called once, from kmain()
+ */
void thread_init_early(void)
{
int i;
@@ -449,6 +556,11 @@
current_thread = t;
}
+/**
+ * @brief Complete thread initialization
+ *
+ * This function is called once at boot time
+ */
void thread_init(void)
{
#if PLATFORM_HAS_DYNAMIC_TIMER
@@ -456,11 +568,19 @@
#endif
}
+/**
+ * @brief Change name of current thread
+ */
void thread_set_name(const char *name)
{
strlcpy(current_thread->name, name, sizeof(current_thread->name));
}
+/**
+ * @brief Change priority of current thread
+ *
+ * See thread_create() for a discussion of priority values.
+ */
void thread_set_priority(int priority)
{
if (priority < LOWEST_PRIORITY)
@@ -470,6 +590,13 @@
current_thread->priority = priority;
}
+/**
+ * @brief Become an idle thread
+ *
+ * This function marks the current thread as the idle thread -- the one which
+ * executes when there is nothing else to do. This function does not return.
+ * This function is called once at boot time.
+ */
void thread_become_idle(void)
{
thread_set_name("idle");
@@ -478,6 +605,9 @@
idle_thread_routine();
}
+/**
+ * @brief Dump debugging info about the specified thread.
+ */
void dump_thread(thread_t *t)
{
dprintf(INFO, "dump_thread: t %p (%s)\n", t, t->name);
@@ -493,6 +623,9 @@
dprintf(INFO, "\n");
}
+/**
+ * @brief Dump debugging info about all threads
+ */
void dump_all_threads(void)
{
thread_t *t;
@@ -504,7 +637,17 @@
exit_critical_section();
}
-/* wait queue */
+/** @} */
+
+
+/**
+ * @defgroup wait Wait Queue
+ * @{
+ */
+
+/**
+ * @brief Initialize a wait queue
+ */
void wait_queue_init(wait_queue_t *wait)
{
wait->magic = WAIT_QUEUE_MAGIC;
@@ -526,6 +669,24 @@
return INT_NO_RESCHEDULE;
}
+/**
+ * @brief Block until a wait queue is notified.
+ *
+ * This function puts the current thread at the end of a wait
+ * queue and then blocks until some other thread wakes the queue
+ * up again.
+ *
+ * @param wait The wait queue to enter
+ * @param timeout The maximum time, in ms, to wait
+ *
+ * If the timeout is zero, this function returns immediately with
+ * ERR_TIMED_OUT. If the timeout is INFINITE_TIME, this function
+ * waits indefinitely. Otherwise, this function returns with
+ * ERR_TIMED_OUT at the end of the timeout period.
+ *
+ * @return ERR_TIMED_OUT on timeout, else returns the return
+ * value specified when the queue was woken by wait_queue_wake_one().
+ */
status_t wait_queue_block(wait_queue_t *wait, time_t timeout)
{
timer_t timer;
@@ -561,6 +722,20 @@
return current_thread->wait_queue_block_ret;
}
+/**
+ * @brief Wake up one thread sleeping on a wait queue
+ *
+ * This function removes one thread (if any) from the head of the wait queue and
+ * makes it executable. The new thread will be placed at the head of the
+ * run queue.
+ *
+ * @param wait The wait queue to wake
+ * @param reschedule If true, the newly-woken thread will run immediately.
+ * @param wait_queue_error The return value which the new thread will receive
+ * from wait_queue_block().
+ *
+ * @return The number of threads woken (zero or one)
+ */
int wait_queue_wake_one(wait_queue_t *wait, bool reschedule, status_t wait_queue_error)
{
thread_t *t;
@@ -598,6 +773,21 @@
return ret;
}
+
+/**
+ * @brief Wake all threads sleeping on a wait queue
+ *
+ * This function removes all threads (if any) from the wait queue and
+ * makes them executable. The new threads will be placed at the head of the
+ * run queue.
+ *
+ * @param wait The wait queue to wake
+ * @param reschedule If true, the newly-woken threads will run immediately.
+ * @param wait_queue_error The return value which the new thread will receive
+ * from wait_queue_block().
+ *
+ * @return The number of threads woken (zero or one)
+ */
int wait_queue_wake_all(wait_queue_t *wait, bool reschedule, status_t wait_queue_error)
{
thread_t *t;
@@ -641,6 +831,11 @@
return ret;
}
+/**
+ * @brief Free all resources allocated in wait_queue_init()
+ *
+ * If any threads were waiting on this queue, they are all woken.
+ */
void wait_queue_destroy(wait_queue_t *wait, bool reschedule)
{
#if THREAD_CHECKS
@@ -651,6 +846,19 @@
wait->magic = 0;
}
+/**
+ * @brief Wake a specific thread in a wait queue
+ *
+ * This function extracts a specific thread from a wait queue, wakes it, and
+ * puts it at the head of the run queue.
+ *
+ * @param t The thread to wake
+ * @param reschedule If true, the newly-woken threads will run immediately.
+ * @param wait_queue_error The return value which the new thread will receive
+ * from wait_queue_block().
+ *
+ * @return ERR_NOT_BLOCKED if thread was not in any wait queue.
+ */
status_t thread_unblock_from_wait_queue(thread_t *t, bool reschedule, status_t wait_queue_error)
{
enter_critical_section();