A bunch of more docs 😄

Author: viktorpopp

kernel/src/lib/bitmap.h

@@ -1,6 +1,26 @@
 #pragma once
 #include <stdint.h>
 
+/**
+ * @brief Clears the specified bit in a bitmap.
+ *
+ * @param bitmap Pointer to the bitmap.
+ * @param bit The bit to clear.
+ */
 void bitmap_clear(uint8_t *bitmap, uint64_t bit);
+
+/**
+ * @brief Sets the specified bit in a bitmap.
+ *
+ * @param bitmap Pointer to the bitmap.
+ * @param bit The bit to set.
+ */
 void bitmap_set(uint8_t *bitmap, uint64_t bit);
+
+/**
+ * @brief Gets the specified bit in a bitmap.
+ *
+ * @param bitmap Pointer to the bitmap.
+ * @param bit The bit to get.
+ */
 uint8_t bitmap_get(uint8_t *bitmap, uint64_t bit);

kernel/src/lib/string.h

@@ -1,6 +1,8 @@
 #pragma once
 #include <stddef.h>
 
+// Standard C stuff.
+
 void *memcpy(void *restrict dest, const void *restrict src, size_t n);
 void *memset(void *s, int c, size_t n);
 void *memmove(void *dest, const void *src, size_t n);

kernel/src/mem/mmutil.h

@@ -11,7 +11,9 @@ extern uint64_t __limine_requests_start, __limine_requests_end;
 #define VIRT_BASE   address_request.response->virtual_base
 #define PHYS_BASE   address_request.response->physical_base
 
+// Makes sure an addess is in the higher half.
 #define HIGHER_HALF(addr)                                                                          \
     ((void *)((uint64_t)(addr) < HHDM_OFFSET ? (uint64_t)(addr) + HHDM_OFFSET : (uint64_t)(addr)))
+// Translate a address in the higher half to physical.
 #define PHYSICAL(addr)                                                                             \
     ((void *)((uint64_t)(addr) >= HHDM_OFFSET ? (uint64_t)(addr) - HHDM_OFFSET : (uint64_t)(addr)))

kernel/src/mem/pmm.h

@@ -5,7 +5,28 @@
 
 #define PAGE_SIZE 0x1000
 
+/**
+ * @brief Initializes the Physical Memory Manager
+ *
+ * @param memmap_request Pointer to the Limine memory map request.
+ * @param hhdm_request Pointer to the Limine HHDM request.
+ */
 void pmm_init(volatile struct limine_memmap_request *memmap_request,
               volatile struct limine_hhdm_request *hhdm_request);
+
+/**
+ * @brief Allocates a physical frame
+ *
+ * @param n The amount of frames to allocate
+ * @param higher_half Specifies if the HHDM offset should be added to the pointer returned.
+ * @return Physical (or virtual if `higher_half` is true) address of the alloacted frame.
+ */
 void *palloc(size_t n, bool higher_half);
+
+/**
+ * @brief Frees a physical frame
+ *
+ * @param addr The address of the frame (can be either virtual or physical).
+ * @param n The amount of frames to free.
+ */
 void pfree(void *addr, size_t n);

kernel/src/mem/vmm.h

@@ -39,5 +39,16 @@ typedef struct vmm_node_t
     struct vmm_node_t *next;
 } vmm_node_t;
 
+/**
+ * @brief Initializes (and allocates) a new VMC.
+ *
+ * @param pml4 The pagemap it will use.
+ * @param flags Flags for the root VMO.
+ * @return Pointer to the new VMC.
+ */
 vmm_context_t *vmm_context_init(uint64_t *pml4, uint64_t flags);
+
+/**
+ * @brief Initializes the Virtual Memory Manager
+ */
 void vmm_init();

kernel/src/test/test.h

@@ -5,6 +5,9 @@
 
 #define TEST_SECTION __attribute__((section(".testcases"), used))
 
+/**
+ * @brief Representing a test result
+ */
 typedef struct
 {
     const char *name;
@@ -16,23 +19,37 @@ typedef struct
     uint32_t line;
 } test_result_t;
 
+/**
+ * @brief Representing a test function
+ */
 typedef void (*test_func_t)(test_result_t *result);
 
+/**
+ * @brief Representing a test case.
+ */
 typedef struct
 {
     const char *name;
     const char *group;
     test_func_t func;
 } test_case_t;
 
+/**
+ * @brief Macro for easily defining a test case.
+ */
 #define TEST(GROUP, NAME, BODY)                                                                    \
     static void __test_func_##NAME(test_result_t *result);                                         \
     static const test_case_t __test_case_##NAME TEST_SECTION = {                                   \
         .name = #NAME, .group = #GROUP, .func = __test_func_##NAME};                               \
     static void __test_func_##NAME(test_result_t *result) BODY
 
+/**
+ * @brief Runs every test (if `UNIT_TEST_ENABLED` is defined).
+ */
 void test_run_all();
 
+// === Basic Testing Things ===
+
 #define ASSERT_TRUE(expr)                                                                          \
     do                                                                                             \
     {                                                                                              \

kernel/src/util/kprintf.h

@@ -1,6 +1,17 @@
 #pragma once
 #include <__stdarg_va_list.h>
 
+/**
+ * @brief Initializes `kprintf`
+ */
 void _kprintf_init();
+
+/**
+ * @brief Prints the specified format to the term and serial devices.
+ *
+ * @param fmt The format to print.
+ * @param ... Other stuff (idk what it is called)
+ * @return Length of printed buffer (max 1024 bytes) (-1 on fail)
+ */
 int kprintf(const char *fmt, ...);
 int kvprintf(const char *fmt, va_list args);

kernel/src/util/qemu.h

@@ -4,4 +4,9 @@
 #define QEMU_EXIT_SUCCESS 0x10
 #define QEMU_EXIT_FAILURE 0x11
 
+/**
+ * @brief Exits QEMU.
+ *
+ * @param code The error code. Use the above.
+ */
 void qemu_exit(uint8_t code);