thread: add basic intro blurb

Author: fincs

docs/groups.h

@@ -45,7 +45,7 @@
 		@brief Interrupt handling
 	*/
 	/*! @defgroup thread Threads
-		@brief Thread management @see @ref thrd_intro
+		@brief Thread management
 	*/
 	/*! @defgroup sync Sync
 		@brief Synchronization primitives
@@ -57,7 +57,7 @@
 //! @}
 
 /*! @defgroup hw Hardware
-	@brief Low-level device wrappers
+	@brief Low-level system devices
 	@{
 */
 
@@ -79,7 +79,7 @@
 //! @}
 
 /*! @defgroup dev Devices
-	@brief High-level device drivers
+	@brief Device drivers and associated APIs
 	@{
 */
 

docs/pages.h

@@ -1,9 +1,5 @@
 #pragma once
 
-/*! @page thrd_intro Threading
-	@brief General overview of calico's threading system
-	@include{doc} "threads.md"
-*/
 /*! @page license License
 	@brief Licensing information about calico
 	@include{doc} "../COPYING"

docs/threads.md

@@ -5,6 +5,22 @@
 #include "tick.h"
 
 /*! @addtogroup thread
+
+	Calico provides a simple preemptive multithreading system. Each thread is
+	assigned a priority level and has its own execution state, allowing software
+	to be better structured by having different processing tasks each in its own
+	thread. Threads may wait on events such as interrupts. Calico ensures at all
+	times that the currently running thread is always the highest priority thread
+	that can run. If any event occurs that causes a higher priority thread to
+	become runnable, Calico will preempt the current thread. Unlike in common PC
+	operating systems, Calico presently does not implement timeslicing to share
+	the CPU between threads of the same priority; meaning it is necessary to
+	explicitly yield control of the CPU if any such threads exist.
+
+	While Calico provides its own threading API, it is also possible to use standard
+	threading APIs such as POSIX threads or C++ threads. These APIs are in fact
+	preferred when working with cross platform projects.
+
 	@{
 */
 
@@ -14,8 +30,8 @@ typedef struct Thread Thread;
 
 //! List of blocked threads, used as a building block for synchronization primitives
 typedef struct ThrListNode {
-	Thread* next;
-	Thread* prev;
+	Thread* next; //!< @private
+	Thread* prev; //!< @private
 } ThrListNode;
 
 //! @private
@@ -46,8 +62,8 @@ typedef int (* ThreadFunc)(void* arg);
 struct Thread {
 	ArmContext ctx;      //!< CPU context structure
 
-	void* tp;            //!< Virtual thread pointer register
-	void* impure;        //!< @private
+	void* tp;            //!< Virtual thread-local segment register
+	void* impure;        //!< Pointer to per-thread C standard library state
 
 	Thread* next;        //!< @private
 	ThrStatus status;    //!< @private