From 9e63f336cf93e3caa49458c48085f5bd0c5b87d6 Mon Sep 17 00:00:00 2001 From: antifallobst Date: Thu, 27 Apr 2023 13:04:22 +0200 Subject: [PATCH] noxos (docs): documented pipes and new process operations (pause/start) --- .../noxos/docs/codebase/proc/pipe.h.md | 46 +++++++++++++++++ .../noxos/docs/codebase/proc/process.h.md | 51 +++++++++++++------ .../noxos/docs/codebase/proc/scheduler.h.md | 6 +++ 3 files changed, 88 insertions(+), 15 deletions(-) create mode 100644 content/projects/noxos/docs/codebase/proc/pipe.h.md diff --git a/content/projects/noxos/docs/codebase/proc/pipe.h.md b/content/projects/noxos/docs/codebase/proc/pipe.h.md new file mode 100644 index 0000000..103dbd2 --- /dev/null +++ b/content/projects/noxos/docs/codebase/proc/pipe.h.md @@ -0,0 +1,46 @@ +--- +title: "pipe.h" +summary: data streams between processes +--- + +Pipes are data streams between processes. + +# `PIPE_MAX_SENDERS` - macro +The maximum amount of processes, which can write data to one pipe. + +# `PIPE_STD_STREAM_SIZE` - macro +The size of a pipes stream buffer, in bytes. + +# `pipe_T` - struct +| Name | Type | Description | +|----------------|-------------------------------|---------------------------------------------------------| +| stream | stream_T* | The stream, where the pipes data is saved. | +| receiver | process_T* | The process which is allowed to read from the pipe. | +| senders | process_T* [PIPE_MAX_SENDERS] | The processes which are allowed to write to the pipe. | +| senders_bitmap | bitmap_T | Indicates which fields of _senders_ are currently used. | + + +# `pipe_init(pipe*, receiver*)` - function (void) +Initializes **_pipe_** and allocates a stream for it. + +# `pipe_destruct(pipe*)` - function (void) +Destructs **_pipe_** and frees all of its resources. + +# `pipe_add_sender(pipe*, sender*)` - function (bool) +Adds **_sender_** to the sender list of **_pipe_**. +Returns if the operation was successful. + +# `pipe_remove_sender(pipe*, sender*)` - function (void) +Removes **_sender_** from the sender list of **_pipe_**. + +# `pipe_write(pipe*, buffer_in*, n)` - function (uint64_t) +Writes at most **_n_** bytes from **_buffer_in_** into **_pipe_**. +Returns the amount of bytes that were actually written. +If the amount of actually written bytes is smaller than **_n_** all sender processes of **_pipe_** will be _PIPE_OUT blocked_. +If the receiver is _PIPE_IN blocked_ the blocker will be removed. + +# `pipe_read(pipe*, buffer_out*, n)` - function (uint64_t) +Reads at most **_n_** bytes from **_buffer_in_** into **_pipe_**. +Returns the amount of bytes that were actually read. +If the amount of actually read bytes is smaller than **_n_** the receiver process of **_pipe_** will be _PIPE_IN blocked_. +If the senders are _PIPE_OUT blocked_ the blockers will be removed. diff --git a/content/projects/noxos/docs/codebase/proc/process.h.md b/content/projects/noxos/docs/codebase/proc/process.h.md index d46804b..9764527 100644 --- a/content/projects/noxos/docs/codebase/proc/process.h.md +++ b/content/projects/noxos/docs/codebase/proc/process.h.md @@ -20,23 +20,32 @@ These are standard pids - **None** - This pid is invalid, like `NULL` is an invalid pointer - **Kernel** - The kernels' main process +# `process_blockers_E` - enum +- **PIPE_OUT** - This blocker becomes activated, when the process tries to write to a pipe, but the pipe has not enough space for the data. It becomes deactivated, when the pipe has space to fit the rest of the data. +- **PIPE_IN** - This blocker becomes activated, when the process tries to read from a pipe, but the pipe has not the requested amount of data. It becomes deactivated, when the pipe contains data again. + # `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 | +| 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 | +| fd_array | file_descriptor_array_T* | Contains the open file descriptors of the process. | +| stdout | pipe_T* | Pointer to the pipe, where **stdout** writes to. | +| stdin | pipe_T | The pipe, where **stdin** reads from. | +| stderr | pipe_T* | Pointer to the pipe, where **stderr** writes to. | +| waiting | bitmap_T | A bitmap of process blockers. If this is greater 0 the process is blocked by something. | +| 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) @@ -56,6 +65,18 @@ If it finds one it returns it, else it returns [THREAD_ID_INVALID](https://nerdc # `process_clear_thread_id(process, id)` - function (void) Frees the thread **_id_** and makes it request-able again. +# `process_pause_pid(pid)` - function (void) +Resolves the pids process and performs `process_pause` on it. + +# `process_pause(process)` - function (void) +Pauses **_process_** and all of its threads. + +# `process_start_pid(pid)` - function (void) +Resolves the pids process and performs `process_start` on it. + +# `process_start(process)` - function (void) +Starts **_process_** and all of its threads. + # `process_kill_pid(pid)` - function (void) Resolves the pids process and performs `process_kill` on it. diff --git a/content/projects/noxos/docs/codebase/proc/scheduler.h.md b/content/projects/noxos/docs/codebase/proc/scheduler.h.md index 15e0440..d948598 100644 --- a/content/projects/noxos/docs/codebase/proc/scheduler.h.md +++ b/content/projects/noxos/docs/codebase/proc/scheduler.h.md @@ -63,6 +63,12 @@ Pauses and unregisters **_thread_**. #### `scheduler_register_process(process)` - function (pid_t) Reqisters **_process_** and returns its pid. +#### `scheduler_pause_process(process)` - function (void) +Pauses **_process_** and its threads. + +#### `scheduler_start_process(process)` - function (void) +Starts **_process_** and its threads. + #### `scheduler_kill_process(process)` - function (void) Kills **_process_** and its threads and childs.