noxos (docs): merged 'utils' docs from .wiki

content/projects/noxos/docs/codebase/utils/bitmap.h.md

@@ -0,0 +1,30 @@
+---
+title: "bitmap.h"
+summary: "utils to handle bitmaps"
+---
+
+# `bitmap_T` - struct
+
+| Name      | Type     | Description                           |
+|-----------|----------|---------------------------------------|
+| size      | uint32_t | The size of _buffer_ (in bytes)       |
+| size_bits | uint32_t | The amount of storable bits           |
+| buffer    | uint8_t* | The buffer, where the bits are stored |
+
+# `bitmap_init_from_buffer(buffer, size)` - function (bitmap_T)
+Creates a bitmap object from a given buffer and size
+
+# `bitmap_init(size)` - function (bitmap_T)
+Allocates memory to hold a bitmap in the given size and returns a [bitmap_T](https://nerdcult.net/projects/noxos/docs/codebase/utils/bitmap.h/#bitmap_t---struct) with that buffer and size.
+
+# `bitmap_destruct(bitmap*)` - function (void)
+Frees the memory of the given bitmap created with [bitmap_init](https://nerdcult.net/projects/noxos/docs/codebase/utils/bitmap.h/#bitmap_initsize---function-bitmap_t).
+
+# `bitmap_set(bitmap*, index, value)` - function (bool)
+Sets the bit at the given index in the given bitmap to the given boolean value.
+Returns **false**, if the index is out of the bitmaps size bounds.
+Returns **true**, if the operation was successful.
+
+# `bitmap_get(bitmap*, index)` - function (bool)
+Returns the boolean value stored at the given index in the given bitmap.
+Always returns **false**, if the index is out of the bitmaps size bounds.

content/projects/noxos/docs/codebase/utils/core.h.md

@@ -0,0 +1,19 @@
+---
+title: "core.h"
+summary: "all the utils, which I didn't know how to name"
+---
+
+# `CORE_INTERRUPTABLE_HALT_WHILE(a)` - macro
+This halts until **_a_** is true.
+Used when working with blocking variables in e.g. thread safe functions.
+To avoid deadlocks, this macro won't halt, while the system is handling an interrupt.
+
+# `CORE_HALT_WHILE(a)` - macro
+This halts until **_a_** is true.
+Used when working with blocking variables in e.g. thread safe functions.
+
+**Warning:** When a function containing this macro is used while handling an interrupt,
+this could cause deadlocks, consider using [CORE_INTERRUPTABLE_HALT_WHILE](https://nerdcult.net/projects/noxos/docs/codebase/utils/core.h/#core_interruptable_halt_whilea---macro) instead.
+
+# `CORE_HALT_FOREVER` - macro
+This halts forever and warns about this in the log.

content/projects/noxos/docs/codebase/utils/io.h.md

@@ -0,0 +1,16 @@
+---
+title: "io.h"
+summary: "provides basic input/output functionalities."
+---
+
+# `io_out_byte(port, data)` - function (void)
+Writes one byte of **_data_** to **_port_**.
+This is a wrapper around the assembly `outb` instruction.
+
+# `io_in_byte(port)` - function (uint8_t)
+Reads one byte from **_port_** and returns it.
+This is a wrapper around the assembly `inb` instruction.
+
+# `io_wait()` - function (void)
+Waits one IO cycle.
+Should be used to give the devices enough time to respond.

content/projects/noxos/docs/codebase/utils/logger.h.md

@@ -0,0 +1,15 @@
+---
+title: "logger.h"
+summary: "functionalities to write logs to QEMU's serial port."
+---
+
+# `log_level_E` - enum
+- **None** - Logs just the message without a prefix
+- **Info** - General information, that could be useful
+- **Debug** - Should only be used to find bugs and removed (or commented out) after the bug is found
+- **Warning** - Used for warnings and not important errors
+- **Error** - Used for Fatal Errors / Will be printed to the screen (graphics driver is not Implemented yet)
+
+# `log(log_level, string, ...)` - function (void)
+Logs the given string to QEMU's log port, the string is prefixed with the log type.
+Format strings are supported.

content/projects/noxos/docs/codebase/utils/math.h.md

@@ -0,0 +1,36 @@
+---
+title: "math.h"
+summary: "mathematical functions, definitions, etc."
+---
+
+# `MAX(a, b)` - macro
+Returns the bigger one of the given values.
+
+# `MIN(a, b)` - macro
+Returns the smaller one of the given values.
+
+# `CEIL_TO(a, b)` - macro
+Aligns **_a_** upwards to **_b_**.
+Example: `CEIL_TO(13, 8)` would return 16, because 16 is the next higher multiple of 8 after 13.
+
+# `FLOOR_TO(a, b)` - macro
+Aligns **_a_** downwards to **_b_**.
+Example: `FLOOR_TO(13, 8)` would return 8, because 8 is the next smaller multiple of 8 before 13.
+
+# `position_T` - struct
+This describes a position in 2D space.
+
+| Name | Description                  |
+|------|------------------------------|
+| x    | X coordinate of the position |
+| y    | Y coordinate of the position |
+
+
+# `pow(base, exponent)` - function (uint64_t)
+Returns the power of `base ^ exponent`.
+
+# `abs(number)` - function (uint64_t)
+Returns the absolute value of **_number_**.
+
+# `octal_string_to_int(string, size)` - function (uint64_t)
+Converts a base-8 **_string_** with length **_size_** into an integer and returns it.

content/projects/noxos/docs/codebase/utils/memory.h.md

@@ -0,0 +1,33 @@
+---
+title: "memory.h"
+summary: "basic memory functionalities"
+---
+
+# `memory_copy(source, destination, num)` - function (void)
+Copies **_num_** bytes from **_source_** to **_destination_**.
+On linux this function is called _memcpy_.
+
+# `memory_set(destination, data, num)` - function (void)
+Sets **_num_** bytes at **_destination_** to **_data_**.
+On linux this function is called _memset_.
+
+# `memory_compare(a, b, num)` - function (bool)
+Compares the first **_num_** bytes at **_a_** and **_b_**.
+Returns **false** if there is a different byte.
+Returns **true** if the data is the same.
+There is a similar function on linux called _memcmp_.
+
+# `memory_allocate(size)` - function (void*)
+Returns the address to a buffer, that is at least **_size_** bytes big.
+On linux this function is called _malloc_.
+
+# `memory_free(address)` - function (void)
+Free the buffer at address and marks it claimable again , this buffer needs to be a buffer, that was created with [memory_allocate](https://nerdcult.net/projects/noxos/docs/codebase/utils/memory.h/#memory_allocatesize---function-void).
+On linux this function is called _free_.
+
+# `memory_allocator_init(base)` - function (void)
+This initializes the heap, where [memory_allocate](https://nerdcult.net/projects/noxos/docs/codebase/utils/memory.h/#memory_allocatesize---function-void) allocates memory.
+
+# `memory_hexdump(address, num)` - function (void)
+Logs **_num_** bytes from **_address_** as 8 byte rows.
+The data is represented in hexadecimal and ascii.

content/projects/noxos/docs/codebase/utils/panic.h.md

@@ -0,0 +1,9 @@
+---
+title: "panic.h"
+summary: "ahhhh - the kernel is burning"
+---
+
+# `panic(state, message)` - function (void)
+This prints out the error message, a stack backtrace and a register dump.
+After that, the kernel halts forever.
+This function is called, when a fatal error occurs

content/projects/noxos/docs/codebase/utils/stdtypes.h.md

@@ -0,0 +1,57 @@
+---
+title: "stdtypes.h"
+summary: "standard type definitions, that are used almost everywhere."
+---
+
+
+#### `uint8_t` - typedef
+8-bit wide unsigned int.
+
+Range: `0` - `255`
+
+#### `int8_t` - typedef
+8-bit wide signed int.
+
+Range: `-128` - `127`
+
+#### `uint16_t` - typedef
+16-bit wide unsigned int.
+
+Range: `0` - `65536`
+
+#### `int16_t` - typedef
+16-bit wide signed int.
+
+Range: `-32768` - `32767`
+
+#### `uint32_t` - typedef
+32-bit wide unsigned int.
+
+Range: `0` - `4294967296`
+
+#### `int32_t` - typedef
+32-bit wide signed int.
+
+Range: `-2147483648` - `2147483647`
+
+#### `uint64_t` - typedef
+64-bit wide unsigned int.
+
+Range: `0` - `18446744073709551616`
+
+#### `int64_t` - typedef
+64-bit wide signed int.
+
+Range: `-9223372036854775808` - `9223372036854775807`
+
+#### `bool` - typedef
+Boolean type, can hold a logical value **true** or **false**.
+
+#### `true` - macro
+Logical **true** value.
+
+#### `false` - macro
+Logical **false** value
+
+#### `NULL` - macro
+A pointer to nowhere.

content/projects/noxos/docs/codebase/utils/string.h.md

@@ -0,0 +1,91 @@
+---
+title: "string.h"
+summary: "basic functions for string manipulation"
+---
+
+#### `string_t` - typedef
+A null-terminated array of chars.
+
+#### `string_length(string)` - function (uint32_t)
+Returns the amount of chars a string has before it's null-terminator.
+
+#### `string_compare(a, b)` - function (bool)
+Returns **true** when the strings **_a_** and **_b_** are equal.
+Returns **false** if they aren't equal.
+
+#### `string_find_next(string, chr)` - function (uint32_t)
+Returns the index of the next character that matches **_chr_** in **_string_**.
+
+#### `string_find_last(string, chr)` - function (uint32_t)
+Returns the index of the last character that matches **_chr_** in **_string_**.
+
+#### `variadic_format_size(string, args)` - function (uint64_t)
+Returns how long a format string with the given pattern (**_string_**) and **_args_** would be.
+Useful to create a big enough buffer before formatting a string.
+
+#### `format_size(string, ...)` - function (uint64_t)
+This calls `variadic_format_size`, but instead of giving it a `va_list` you can give this function the actual arguments.
+
+#### `variadic_format(output, string, args)` - function (void)
+Formats **_string_** with **_args_** and writes the product to **_output_**.
+The rules for format strings are specified on top of this document in the _General concepts_ block.
+
+#### `format(output, string, ...)` - function (void)
+This calls `variadic_format`, but instead of giving it a `va_list` you can give this function the actual arguments.
+
+#### `string_unsigned_dec_to_alpha(string, value)` - function (void)
+Converts the unsigned integer in **_value_** to an alphanumeric string.
+The representation is decimal.
+This string will be written into **_string_**.
+
+#### `string_dec_to_alpha(string, value)` - function (void)
+Converts the signed integer in **_value_** to an alphanumeric string.
+If it is negative it will be prefixed with a hyphen.
+The representation is decimal.
+This string will be written into **_string_**.
+
+#### `string_hex_8bit_to_alpha(string, value)` - function (void)
+Converts the byte in **_value_** to an alphanumeric string.
+The representation is hexadecimal.
+This string will be written into **_string_**.
+
+#### `string_hex_16bit_to_alpha(string, value)` - function (void)
+Converts the word(16-bits) in **_value_** to an alphanumeric string.
+The representation is hexadecimal.
+This string will be written into **_string_**.
+
+#### `string_hex_32bit_to_alpha(string, value)` - function (void)
+Converts the dword(32-bits) in **_value_** to an alphanumeric string.
+The representation is hexadecimal.
+This string will be written into **_string_**.
+
+#### `string_hex_64bit_to_alpha(string, value)` - function (void)
+Converts the qword(64-bits) in **_value_** to an alphanumeric string.
+The representation is hexadecimal.
+This string will be written into **_string_**.
+
+#### `string_bin_to_alpha(string, num_bits, value)` - function (void)
+Converts the data in **_value_** to an alphanumeric string.
+The representation is binary.
+**_num_bits_** specifies how many bits, starting at the least significant bit, will be converted.
+This string will be written into **_string_**.
+
+#### `string_bool_to_alpha(string, value`) - function (void)
+Converts the boolean in **_value_** to an alphanumeric string.
+The representation is `true` or `false`.
+This string will be written into **_string_**.
+
+#### `string_is_char_text(chr)` - function (bool)
+Returns whether the char (**_chr_**) contains text(a-z, A-Z, 0-9, special chars) or not.
+
+#### `string_is_char_number(chr)` - function (bool)
+Returns whether the char (**_chr_**) is a number(0-9) or not.
+
+#### `string_is_char_alpha(chr)` - function (bool)
+Returns whether the char (**_chr_**) is alphanumeric(a-z, A-Z, 0-9) or not.
+
+#### `string_is_char_uppercase(chr)` - function (bool)
+Returns whether the char (**_chr_**) is uppercase(A-Z) or not.
+
+#### `string_is_char_lowercase(chr)` - function (bool)
+Returns whether the char (**_chr_**) is lowercase(a-z) or not.

content/projects/noxos/docs/codebase/utils/symbol.h.md

@@ -0,0 +1,23 @@
+---
+title: "symbol.h"
+summary: "basic functions to define and resolve symbols"
+---
+
+#### `symbol_type_E` - enum
+- **Function**
+- **Variable**
+- **Unknown**
+
+#### `symbol_T` - struct
+
+| Name    | Type                                                                                                    | Description                                                                         |
+|---------|---------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------|
+| name    | [string_t](https://nerdcult.net/projects/noxos/docs/codebase/utils/string.h/#string_t---typedef)        | The name of the symbol (e.g. the name of the kernels entry symbol would be `_start` |
+| type    | [symbol_type_E](https://nerdcult.net/projects/noxos/docs/codebase/utils/symbol.h/#symbol_type_e---enum) | The symbols type (elf types like `File` are of type `Unknown`)                      |
+| address | uint64_t                                                                                                | The symbols address                                                                 |
+
+#### `symbol_resolve_from_name(symbols, num_symbols, name);` - function (symbol_T*)
+This searches **_symbols_** for a symbol with a matching **_name_**.
+
+#### `symbol_resolve_from_rip(symbols, num_symbols, rip);` - function (symbol_T*)
+Give it a list of **_symbols_** and an instruction pointer (**_rip_**) and it will return the symbol (function), where **_rip_** lays in.