From 90fb3069fb2c77502577a8193d8328d28c8cb56c Mon Sep 17 00:00:00 2001 From: antifallobst Date: Thu, 16 Mar 2023 12:56:44 +0100 Subject: [PATCH] noxos (docs): merged 'utils' docs from .wiki --- .../noxos/docs/codebase/utils/bitmap.h.md | 30 ++++++ .../noxos/docs/codebase/utils/core.h.md | 19 ++++ .../noxos/docs/codebase/utils/io.h.md | 16 ++++ .../noxos/docs/codebase/utils/logger.h.md | 15 +++ .../noxos/docs/codebase/utils/math.h.md | 36 ++++++++ .../noxos/docs/codebase/utils/memory.h.md | 33 +++++++ .../noxos/docs/codebase/utils/panic.h.md | 9 ++ .../noxos/docs/codebase/utils/stdtypes.h.md | 57 ++++++++++++ .../noxos/docs/codebase/utils/string.h.md | 91 +++++++++++++++++++ .../noxos/docs/codebase/utils/symbol.h.md | 23 +++++ 10 files changed, 329 insertions(+) create mode 100644 content/projects/noxos/docs/codebase/utils/bitmap.h.md create mode 100644 content/projects/noxos/docs/codebase/utils/core.h.md create mode 100644 content/projects/noxos/docs/codebase/utils/io.h.md create mode 100644 content/projects/noxos/docs/codebase/utils/logger.h.md create mode 100644 content/projects/noxos/docs/codebase/utils/math.h.md create mode 100644 content/projects/noxos/docs/codebase/utils/memory.h.md create mode 100644 content/projects/noxos/docs/codebase/utils/panic.h.md create mode 100644 content/projects/noxos/docs/codebase/utils/stdtypes.h.md create mode 100644 content/projects/noxos/docs/codebase/utils/string.h.md create mode 100644 content/projects/noxos/docs/codebase/utils/symbol.h.md diff --git a/content/projects/noxos/docs/codebase/utils/bitmap.h.md b/content/projects/noxos/docs/codebase/utils/bitmap.h.md new file mode 100644 index 0000000..642ac5d --- /dev/null +++ b/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. diff --git a/content/projects/noxos/docs/codebase/utils/core.h.md b/content/projects/noxos/docs/codebase/utils/core.h.md new file mode 100644 index 0000000..5f7ba59 --- /dev/null +++ b/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. diff --git a/content/projects/noxos/docs/codebase/utils/io.h.md b/content/projects/noxos/docs/codebase/utils/io.h.md new file mode 100644 index 0000000..dffce72 --- /dev/null +++ b/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. diff --git a/content/projects/noxos/docs/codebase/utils/logger.h.md b/content/projects/noxos/docs/codebase/utils/logger.h.md new file mode 100644 index 0000000..b0bd3ff --- /dev/null +++ b/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. diff --git a/content/projects/noxos/docs/codebase/utils/math.h.md b/content/projects/noxos/docs/codebase/utils/math.h.md new file mode 100644 index 0000000..a9909d3 --- /dev/null +++ b/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. diff --git a/content/projects/noxos/docs/codebase/utils/memory.h.md b/content/projects/noxos/docs/codebase/utils/memory.h.md new file mode 100644 index 0000000..c2d0efb --- /dev/null +++ b/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. diff --git a/content/projects/noxos/docs/codebase/utils/panic.h.md b/content/projects/noxos/docs/codebase/utils/panic.h.md new file mode 100644 index 0000000..282de89 --- /dev/null +++ b/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 diff --git a/content/projects/noxos/docs/codebase/utils/stdtypes.h.md b/content/projects/noxos/docs/codebase/utils/stdtypes.h.md new file mode 100644 index 0000000..4932130 --- /dev/null +++ b/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. diff --git a/content/projects/noxos/docs/codebase/utils/string.h.md b/content/projects/noxos/docs/codebase/utils/string.h.md new file mode 100644 index 0000000..6bc031d --- /dev/null +++ b/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. diff --git a/content/projects/noxos/docs/codebase/utils/symbol.h.md b/content/projects/noxos/docs/codebase/utils/symbol.h.md new file mode 100644 index 0000000..7c702a0 --- /dev/null +++ b/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.