Function comments (v1)

src/mem/heap/kheap.c

@@ -23,6 +23,15 @@ static uintptr_t end;
 // Kernel root table (level 4)
 extern uint64_t *kernel_pml4;
 
+/*
+ * kheap_init - Kernel heap initialization
+ *
+ * This function physically allocates and maps enough pages
+ * of memory for KHEAP_SIZE, which is defined in config.h.
+ *
+ * It then creates one big heap block, which will be the
+ * base for a linked list.
+ */
 void kheap_init()
 {
     kheap_start = ALIGN_UP(kernel_virt_base + KERNEL_SIZE, PAGE_SIZE);
@@ -53,6 +62,18 @@ void kheap_init()
     DEBUG("Kernel heap initialized, head=0x%p, size=%u bytes", head, head->size);
 }
 
+/*
+ * kmalloc - Kernel memory allocation
+ * @size: number of bytes to allocate
+ *
+ * Looks for a big enough free block and marks it
+ * as taken. Each block of memory is preceded by
+ * the linked list header.
+ *
+ * Return:
+ * <ptr> - Pointer to at least <size> bytes of usable memory
+ * NULL  - No more memory, or no valid size given
+ */
 void* kmalloc(size_t size)
 {
     // No size, no memory allocated!
@@ -92,6 +113,14 @@ void* kmalloc(size_t size)
     return NULL;
 }
 
+/*
+ * kfree - Kernel memory freeing
+ * @ptr: pointer to memory region to free
+ *
+ * Marks the memory block beginning at <ptr>
+ * as free. Also merges adjacent free blocks
+ * to lessen fragmentation.
+ */
 void kfree(void* ptr)
 {
     // Nothing to free
@@ -113,8 +142,17 @@ void kfree(void* ptr)
     }
 }
 
-// Should alloc enough for a stack (at least 64kb) to be used for a process.
-// Should return a pointer to top of the stack (as stack grows DOWNWARDS)
+/*
+ * kalloc_stack - Stack memory allocation
+ *
+ * Allocates a memory region of at least PROCESS_STACK_SIZE,
+ * to be used as a stack for a process. The pointer returned
+ * points to the end of the region, as the stack grows downwards.
+ *
+ * Return:
+ * <ptr> - Pointer to a region after at least PROCESS_STACK_SIZE bytes of usable memory
+ * NULL  - No more memory
+ */
 void* kalloc_stack()
 {
     uint8_t* ptr = kmalloc(PROCESS_STACK_SIZE); // As it's out of kmalloc, stack is already mapped into kernel space