From f6af4061fd38d01b45cfd2682054fcb5bec73a1e Mon Sep 17 00:00:00 2001
From: antifallobst <antifallobst@systemausfall.org>
Date: Sun, 19 Feb 2023 17:47:46 +0100
Subject: [PATCH] docs: documented the scheduler

---
 .wiki/Kernel-documentation.md | 85 +++++++++++++++++++++++++++++++++++
 1 file changed, 85 insertions(+)

diff --git a/.wiki/Kernel-documentation.md b/.wiki/Kernel-documentation.md
index cfa6591..b4a9341 100644
--- a/.wiki/Kernel-documentation.md
+++ b/.wiki/Kernel-documentation.md
@@ -509,6 +509,91 @@ The default IDT configuration loaded when the IDT gets initialized.
 This function fills all the interrupt gates (handlers) into the IDT and loads it.
 
 
+## proc
+
+### thread.h
+
+#### `thread_T` - struct
+| Name       | Type        | Description                                                                                      |
+|------------|-------------|--------------------------------------------------------------------------------------------------|
+| state      | cpu_state_T | The last saved state of the thread. ( -> _context switching_)                                    |
+| cpu_time   | uint64_t    | The amount of cpu time the thread had. (currently the amount of context switches the thread had) |
+| stack      | void*       | The bottom of the threads stack                                                                  |
+| stack_size | uint32_t    | The size of the threads stack (in bytes)                                                         |
+| prev       | thread_T*   | The previous thread in the scheduling queue (**should only be accessed by the scheduler!**)      |
+| next       | thread_T*   | The next thread in the scheduling queue (**should only be accessed by the scheduler!**)          |
+
+
+#### `thread_spawn(function)` - function (thread_T*)
+Allocates a `thread_T` and registers it in the scheduler.
+The thread starts execution at **_function_**.
+The for the thread allocated stack has a size of 16 KB (4 Pages).
+The thread still needs to be started with a `thread_start` call.
+Returns a pointer to the created thread.
+
+#### `thread_spawn_from_state(state)` - function (thread_T*)
+Allocates a `thread_T` and registers it in the scheduler.
+The threads' _cpu_state_ is copied from **_state_**.
+This won't allocate a stack for the stack.
+The thread still needs to be started with a `thread_start` call.
+Returns a pointer to the created thread.
+This function should be avoided.
+
+#### `thread_start(thread)` - function (void)
+Starts/unpauses **_thread_**.
+
+#### `thread_pause(thread)` - function (void)
+Pauses **_thread_**.
+
+#### `thread_kill(thread)` - function (void)
+Kills **_thread_**.
+The threads stack and `thread_T` structure will be freed.
+
+### scheduler.h
+
+#### `scheduler_T` - struct
+| Name           | Type      | Description                                                        |
+|----------------|-----------|--------------------------------------------------------------------|
+| num_threads    | uint32_t  | Total amount of currently spawned threads                          |
+| running_thread | thread_T* | A pointer to the currently running thread.                         |
+| blocked        | bool      | Set to true, while switching the context. Thread safety mechanism. |
+| initialized    | bool      | Set to true, if the scheduler is initialized and started.          |
+
+#### `scheduler_init()` - function (void)
+Initializes the scheduler and performs a `scheduler_start` kernel syscall.
+After this function, the whole kernel is in scheduling mode.
+
+#### `scheduler_start(state)` - function (cpu_state_T*)
+Creates and starts a thread from **_state_**.
+It returns the result of a context switch, I forgot, why I did it like that.
+This is basically the backend for the `scheduler_start` kernel syscall.
+
+#### `scheduler_is_initialized()` - function (bool)
+Returns if the scheduler is initialized (and running) or not.
+
+#### `scheduler_register_thread(thread)` - function (thread_T*)
+Registers **_thread_** in the scheduler.
+
+#### `scheduler_pause_thread(thread)` - function (void)
+Pauses **_thread_**, by removing it from the scheduling queue.
+
+**Potential Bug:** if **_thread_** was the currently running thread,
+this could cause issues, because it's _prev_ and _next_ values are nulled.
+
+#### `scheduler_start_thread(thread)` - function (void)
+Starts **_thread_**, by linking it into the scheduling queue.
+
+#### `scheduler_kill_thread(thread)` - function (void)
+Pauses and unregisters **_thread_**.
+
+#### `scheduler_get_current_thread()` - function (thread_T*)
+Returns a pointer to the currently running thread.
+
+#### `scheduler_switch_context(state)` - function (cpu_state_T*)
+Saves **_state_** in the running threads _state_ value and increments their _cpu_time_ value.
+Then it sets the next thread as the running thread and returns its _state_.
+This needs to be called from an interrupt handler, for the returned state to be loaded.
+
 ## utils
 
 ### bitmap.h