From f880939eb5f1b5e70b15d6614cc440c09a0d9fd1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matteo=20Gm=C3=BCr?= Date: Sun, 1 Dec 2024 13:57:05 +0000 Subject: Add doxygen comments for linked list helper methods. --- .../arch/memory/heap/linked_list_allocator.hpp | 41 ++++++++++++++++++---- 1 file changed, 34 insertions(+), 7 deletions(-) diff --git a/arch/x86_64/include/arch/memory/heap/linked_list_allocator.hpp b/arch/x86_64/include/arch/memory/heap/linked_list_allocator.hpp index 7432561..71e495a 100644 --- a/arch/x86_64/include/arch/memory/heap/linked_list_allocator.hpp +++ b/arch/x86_64/include/arch/memory/heap/linked_list_allocator.hpp @@ -7,7 +7,7 @@ namespace teachos::arch::memory::heap { /** * @brief Sorted by address list of memory holes (free memory). Uses free holes itself to save the information, - * containing the size and pointer to the next hole. Resulting in a single linked list. + * containing the size and pointer to the next hole. Resulting in a singly linked list. */ struct linked_list_allocator { @@ -46,20 +46,47 @@ namespace teachos::arch::memory::heap auto constexpr min_allocatable_size() -> std::size_t { return sizeof(memory_block); } /** - * @brief Splits the given hole into two, where the latter block keeps beeing free and the first part will be used - * for the allocation. + * @brief Splits the given free memory block into two, where the latter block keeps being free and the first part + * will be used for the allocation. * - * @param current_block Hole we want to split. - * @param size Size we want to allocate at the start of the hole. + * @param current_block Free memory block we want to split. + * @param size Size we want to allocate at the start of the free memory block. * - * @return Address of the hole we just split. + * @return Previous start address of the memory block we just split. */ auto split_free_memory_block(memory_block *& current_block, std::size_t size) -> void *; + /** + * @brief Combines multiple free memory blocks into one if they are adjacent. + * + * @note The internal algorithm for recombination functions like this: + * 1. Check if there is even any memory left, if not the first entry of our linked list should be a nullptr and we + * can therefore set the first entry to our newly created entry. This entry is created in the now deallocated memory + * area. + * 2. If there are more blocks but neither the previous nor the current block are adjacent, we simply create a new + * free memory block of the given size and set the previous next to our block and the next of our block to the + * current block. + * 3. If the current block is adjacent the start address of the newly created block stays the same, but the size + * increases by the amount in the current memory block header. After reading it we also clear the header. + * 4. If the previous block is adjacent the size of the previous block simply increases to include the given size as + * well. + * + * @param previous_block Free memory block before the block to deallocate in our heap memory. + * @param current_block Free memory block after the block to deallocate in our heap memory. + * @param pointer Block to deallocate. + * @param size Size of the block we want to deallocate. + */ auto coalesce_free_memory_block(memory_block *& previous_block, memory_block *& current_block, void * pointer, std::size_t size) -> void; - // We cannot call delete, because it causes "undefined reference to `sbrk`". + /** + * @brief Clears the memory of the previous memory block header. + * + * @note Done so the given pointer can be reused to construct other classes into, without having the old values. + * Required because we cannot call delete, because it causes "undefined reference to `sbrk`". + * + * @param pointer Address we want to clear the memory block header at (16 bytes) + */ auto clear_memory_block_header(void * pointer) -> void; std::size_t heap_start; ///< Start of the allocatable heap area -- cgit v1.2.3