From c507f15fb8b3936f4e08e0093ef57694f3747ec9 Mon Sep 17 00:00:00 2001 From: antifallobst Date: Thu, 16 Mar 2023 12:12:05 +0100 Subject: [PATCH] noxos (docs): merged 'proc' docs from .wiki --- .../noxos/docs/codebase/proc/_index.md | 55 ++++++++++++- .../noxos/docs/codebase/proc/process.h.md | 64 +++++++++++++++ .../noxos/docs/codebase/proc/scheduler.h.md | 81 +++++++++++++++++++ .../noxos/docs/codebase/proc/thread.h.md | 44 ++++++++++ 4 files changed, 243 insertions(+), 1 deletion(-) create mode 100644 content/projects/noxos/docs/codebase/proc/process.h.md create mode 100644 content/projects/noxos/docs/codebase/proc/scheduler.h.md create mode 100644 content/projects/noxos/docs/codebase/proc/thread.h.md diff --git a/content/projects/noxos/docs/codebase/proc/_index.md b/content/projects/noxos/docs/codebase/proc/_index.md index e9c9a68..1e7ae58 100644 --- a/content/projects/noxos/docs/codebase/proc/_index.md +++ b/content/projects/noxos/docs/codebase/proc/_index.md @@ -1,3 +1,56 @@ --- title: "proc" ---- \ No newline at end of file +--- + +The general processing structure is a bit more complex, +so I've split the schematics into multiple parts. + +Processes Schematic: +``` ++----------------+ +| Kernel Process | <----+ +| [Threads] | | ++----------------+ | + | [Parent] + [Childs] | + | +--------+--------+ + v / \ + +-----------+ +-----------+ + | Process 1 | --[Next]-> | Process 2 | + | [Threads] | <-[Prev]-- | [Threads] | . . . + +-----------+ +-----------+ + | | + [Childs] [Childs] + | | + v v + . . . . . . +``` + +Thread Schematics (processes view): +``` ++---------+ +| Process | <-------+ ++---------+ | + | [Process] + [Threads] | + | +--------+--------+ + v / \ ++----------+ +----------+ +| Thread 1 | --[LocalNext]-> | Thread 2 | +| | <-[LocalPrev]-- | | . . . ++----------+ +----------+ +``` + +Thread schematics (schedulers view): +``` + [RunningThread] + | + v + +----------+ +----------+ +----------+ ++---> | Thread 1 | --[GlobalNext]-> | Thread 2 | --[GlobalNext]-> | Thread 3 | . . . ----+ +| +-- | | <-[GlobalPrev]-- | | <-[GlobalPrev]-- | | . . . <-+ | +| | +----------+ +----------+ +----------+ | | +| | | | +| +------------------------------------[GlobalPrev]------------------------------------+ | ++--------------------------------------[GlobalNext]--------------------------------------+ +``` diff --git a/content/projects/noxos/docs/codebase/proc/process.h.md b/content/projects/noxos/docs/codebase/proc/process.h.md new file mode 100644 index 0000000..d46804b --- /dev/null +++ b/content/projects/noxos/docs/codebase/proc/process.h.md @@ -0,0 +1,64 @@ +--- +title: "process.h" +summary: "processes are the containers, in which threads are organized" +--- + +# `MAX_THREADS_PER_PROCESS` - macro +The maximum amount of threads a process can have. +This limitation is just for the bitmap, +the overall processing structure would be capable of processes with unlimited threads, in theory. + +# `THREAD_ID_INVALID` - macro +If [process_get_thread_id](https://nerdcult.net/projects/noxos/docs/codebase/proc/process.h/#process_get_thread_idprocess---function-int32_t) returns this, the process can't spawn one more thread. + +# `pid_t` - typedef +A typedef for `uint32_t`, used for process identification. +Such an identification number is also called `pid`. + +# `processes_standard_E` - enum +These are standard pids +- **None** - This pid is invalid, like `NULL` is an invalid pointer +- **Kernel** - The kernels' main process + +# `process_T` - struct + +| Name | Type | Description | +|-------------|---------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------| +| name | char[128] | The processes' name | +| id | pid_t | The process-identification number | +| chunk | void* | A pointer to the chunk, where the process is stored in | +| chunk_id | uint32_t | The processes id inside of its chunk | +| page_map | [page_map_T](https://nerdcult.net/projects/noxos/docs/codebase/mm/page_map.h/#page_map_t---struct-page-aligned)* | The processes page map. | +| executable | [elf_executable_T](https://nerdcult.net/projects/noxos/docs/codebase/drivers/elf/elf.h/#elf_executable_t---struct)* | The processes executable | +| num_threads | uint32_t | The amount of spawned threads, that belong to the process | +| threads | void* | A pointer to the processes' first thread | +| thread_ids | bitmap_T(reference needed) | This bitmap keeps track of the local thread ids the process has | +| parent | [process_T](https://nerdcult.net/projects/noxos/docs/codebase/proc/process.h/#process_t---struct)* | The process, that spawned this process | +| childs | [process_T](https://nerdcult.net/projects/noxos/docs/codebase/proc/process.h/#process_t---struct)* | A pointer to the processes' first child process | +| prev | [process_T](https://nerdcult.net/projects/noxos/docs/codebase/proc/process.h/#process_t---struct)* | The previous process | +| next | [process_T](https://nerdcult.net/projects/noxos/docs/codebase/proc/process.h/#process_t---struct)* | The next process | + + +# `process_kernel_spawn(executable)` - function (void) +Spawns the kernels' main process. + +**Warning:** this should only be called once, when initializing the scheduler! + +# `process_spawn(parent, name, executable, buffer)` - function (pid_t) +Spawns a process named **_name_** as child of **_parent_** and returns its pid. +The process gets its own page map with the mappings specified in **_executable_**. +In order to apply these mappings, this function needs the **_buffer_** where the executable was loaded from. + +# `process_get_thread_id(process)` - function (int32_t) +Searches for a free thread id in the process. +If it finds one it returns it, else it returns [THREAD_ID_INVALID](https://nerdcult.net/projects/noxos/docs/codebase/proc/process.h/#thread_id_invalid---macro). + +# `process_clear_thread_id(process, id)` - function (void) +Frees the thread **_id_** and makes it request-able again. + +# `process_kill_pid(pid)` - function (void) +Resolves the pids process and performs `process_kill` on it. + +# `process_kill(process)` - function (void) +Kills **_process_** and all of its threads and child processes. +This will also destruct the `executable` and `page_map` associated with **_process_**. diff --git a/content/projects/noxos/docs/codebase/proc/scheduler.h.md b/content/projects/noxos/docs/codebase/proc/scheduler.h.md new file mode 100644 index 0000000..15e0440 --- /dev/null +++ b/content/projects/noxos/docs/codebase/proc/scheduler.h.md @@ -0,0 +1,81 @@ +--- +title: "scheduler.h" +summary: "the scheduler is responsible for switching between threads and controlling processes" +--- + +#### `scheduler_processes_chunk_T` - struct +These chunks are a combination of static array and linked list. +They store the [process_T](https://nerdcult.net/projects/noxos/docs/codebase/proc/process.h/#process_t---struct) pointer for each valid `pid_t`. + +[scheduler_processes_chunk_T](https://nerdcult.net/projects/noxos/docs/codebase/proc/scheduler.h/#scheduler_processes_chunk_t---struct) + +| Name | Type | Description | +|------------------|------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------| +| processes | [process_T](https://nerdcult.net/projects/noxos/docs/codebase/proc/process.h/#process_t---struct)** | The array of process pointers | +| processes_bitmap | bitmap_T(reference needed) | If a bit in this bitmap is set, the _processes_ entry with the same index is valid | +| num_free_pids | uint32_t | The amount of free slots in this chunk | +| prev | [scheduler_processes_chunk_T](https://nerdcult.net/projects/noxos/docs/codebase/proc/scheduler.h/#scheduler_processes_chunk_t---struct)* | The previous chunk | +| next | [scheduler_processes_chunk_T](https://nerdcult.net/projects/noxos/docs/codebase/proc/scheduler.h/#scheduler_processes_chunk_t---struct)* | The next chunk | + + +#### `scheduler_T` - struct +| Name | Type | Description | +|----------------|------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------| +| num_threads | uint32_t | Total amount of currently spawned threads | +| num_processes | uint32_t | Total amount of currently spawned processes | +| running_thread | [thread_T](https://nerdcult.net/projects/noxos/docs/codebase/proc/thread.h/#thread_t---struct)* | A pointer to the currently running thread. | +| processes | [scheduler_processes_chunk_T](https://nerdcult.net/projects/noxos/docs/codebase/proc/scheduler.h/#scheduler_processes_chunk_t---struct)* | The first processes store chunk | +| 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(boot_info)` - function (void) +Initializes the scheduler and performs a `nx_scheduler_start` kernel syscall. +**_boot_info_** is needed in to spawn the kernels' main process. +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 `nx_scheduler_start` kernel syscall. + +#### `scheduler_is_initialized()` - function (bool) +Returns if the scheduler is initialized (and running) or not. + +#### `scheduler_dump_info(process, indent)` - function (void) +This recursively lists information(pid, name, threads) for all child processes of **_process_**. +**_indent_** is used intern for the recursive calls and should be set to 0 initially. + +#### `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_register_process(process)` - function (pid_t) +Reqisters **_process_** and returns its pid. + +#### `scheduler_kill_process(process)` - function (void) +Kills **_process_** and its threads and childs. + +#### `scheduler_get_process(pid)` - function (process_T*) +Returns the `process_T` pointer that is associated with **_pid_**. + +#### `scheduler_get_current_thread()` - function (thread_T*) +Returns a pointer to the currently running thread. + +#### `scheduler_get_current_process()` - function (process_T*) +Returns a pointer to the currently running threads process. + +#### `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. diff --git a/content/projects/noxos/docs/codebase/proc/thread.h.md b/content/projects/noxos/docs/codebase/proc/thread.h.md new file mode 100644 index 0000000..e4ef39b --- /dev/null +++ b/content/projects/noxos/docs/codebase/proc/thread.h.md @@ -0,0 +1,44 @@ +--- +title: "thread.h" +summary: "threading infrastructure" +--- + +# `thread_T` - struct +| Name | Type | Description | +|-------------|--------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------| +| state | [cpu_state_T](https://nerdcult.net/projects/noxos/docs/codebase/platform/cpu.h/#cpu_state_t---struct)* | The last saved state of the thread ( -> _context switching_(reference needed)) | +| 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) | +| process | [process_T](https://nerdcult.net/projects/noxos/docs/codebase/proc/process.h/#process_t---struct)* | The process, to which the thread belongs to | +| global_prev | [thread_T](https://nerdcult.net/projects/noxos/docs/codebase/proc/thread.h/#thread_t---struct)* | The previous thread in the scheduling queue (**should only be accessed by the scheduler!**) | +| global_next | [thread_T](https://nerdcult.net/projects/noxos/docs/codebase/proc/thread.h/#thread_t---struct)* | The next thread in the scheduling queue (**should only be accessed by the scheduler!**) | +| local_prev | [thread_T](https://nerdcult.net/projects/noxos/docs/codebase/proc/thread.h/#thread_t---struct)* | The previous thread of _process_ (**should only be accessed by the scheduler!**) | +| local_next | [thread_T](https://nerdcult.net/projects/noxos/docs/codebase/proc/thread.h/#thread_t---struct)* | The next thread of _process_ (**should only be accessed by the scheduler!**) | +| local_id | uint32_t | The threads id in its process | + + +# `thread_spawn(function)` - function (thread_T*) +Allocates a [thread_T](https://nerdcult.net/projects/noxos/docs/codebase/proc/thread.h/#thread_t---struct) 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 [thread_start](https://nerdcult.net/projects/noxos/docs/codebase/proc/thread.h/#thread_startthread---function-void). +Returns a pointer to the created thread. + +# `thread_spawn_from_state(state)` - function (thread_T*) +Allocates a [thread_T](https://nerdcult.net/projects/noxos/docs/codebase/proc/thread.h/#thread_t---struct) 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 [thread_start](https://nerdcult.net/projects/noxos/docs/codebase/proc/thread.h/#thread_startthread---function-void). +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](https://nerdcult.net/projects/noxos/docs/codebase/proc/thread.h/#thread_t---struct) structure will be freed.