Handout

kernel/thread/thread.h

@@ -0,0 +1,102 @@
+// vim: set noet ts=4 sw=4:
+
+/*! \file
+ *  \brief \ref Thread abstraction required for multithreading
+ */
+
+/*! \defgroup thread Multithreading
+ *  \brief The Multithreading Subsystem
+ *
+ * The group Multithreading contains all elements that form the foundation
+ * of CPU multiplexing. This module's objective is to provide the abstraction
+ * thread that provides a virtualized CPU for the user's applications.
+ */
+
+#pragma once
+#include "../arch/context.h"
+#include "../object/queue.h"
+#include "../types.h"
+
+/// Stack size for each thread
+constexpr uint32_t STACK_SIZE = 4096;
+
+/*! \brief The Thread is an object used by the scheduler.
+ *  \ingroup thread
+ */
+class Thread {
+   private:
+	/*! \brief pointer to the next element of the readylist
+	 */
+	Thread* queue_link;
+
+	friend class Queue<Thread>;
+	friend class Semaphore;
+	/*! \brief Memory reserved for this threads stack
+	 */
+	alignas(16) char reserved_stack_space[STACK_SIZE];
+
+   protected:
+	/*! \brief Context of the thread, used for saving and restoring the register
+	 * values when context switching.
+	 */
+	Context context;
+
+	/*! \brief The thread's entry point.
+	 *
+	 *  For the first activation of a thread, we need a "return address"
+	 *  pointing to a function that will take care of calling C++ virtual
+	 *  methods (e.g. \ref action()), based on the thread object pointer.
+	 *  For this purpose, we use this `kickoff()` function.
+	 *
+	 *  \note As this function is never actually called, but only executed by
+	 *        returning from the co-routine's initial stack, it may never
+	 * return. Otherwise garbage values from the stack will be interpreted as
+	 *        return address and the system might crash.
+	 *
+	 *  \param param1 Thread to be started
+	 *  \param param2 Second parameter (will be used later)
+	 *  \param param3 Third parameter (will be used later)
+	 */
+	static void kickoff(uintptr_t param1, uintptr_t param2, uintptr_t param3);
+
+   public:
+	/*! \brief Unique thread id */
+	const size_t id;
+
+	/*! \brief Marker for a dying thread
+	 */
+	volatile bool kill_flag;
+
+	/*! \brief Constructor
+	 *  Initializes the context using \ref prepareContext with the thread's
+	 * stack space.
+	 *
+	 */
+	explicit Thread();
+
+	/*! \brief Activates the first thread on this CPU.
+	 *
+	 *  Calling the method starts the first thread on the calling CPU.
+	 *  From then on, \ref Thread::resume() must be used for all subsequent
+	 * context switches.
+	 *
+	 */
+	void go();
+
+	/*! \brief Switches from the currently running thread to the `next` one.
+	 *
+	 *  The values currently present in the callee-saved registers will be
+	 *  stored in this threads context-structure, the corresponding values
+	 *  belonging to `next` thread will be loaded.
+	 *  \param next Pointer to the next thread.
+	 *
+	 */
+	void resume(Thread* next);
+
+	/*! \brief Method that contains the thread's program code.
+	 *
+	 *  Derived classes are meant to override this method to provide
+	 *  meaningful code to be run in this thread.
+	 */
+	virtual void action() = 0;	// XXX: why is this not always pure virtual?
+};