sandbox: memblock: add documentation and license

sandbox/memblock/include/socks/memblock.h

@@ -1,5 +1,26 @@
-#ifndef MEMBLOCK_H_
+/*
-#define MEMBLOCK_H_
+  The Clear BSD License
+
+  Copyright (c) 2023 Max Wash
+  All rights reserved.
+
+  Redistribution and use in source and binary forms, with or without
+  modification, are permitted (subject to the limitations in the disclaimer
+  below) provided that the following conditions are met:
+
+  - Redistributions of source code must retain the above copyright notice,
+    this list of conditions and the following disclaimer.
+
+  - Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in the
+    documentation and/or other materials provided with the distribution.
+  
+  - Neither the name of the copyright holder nor the names of its
+    contributors may be used to endorse or promote products derived from this
+    software without specific prior written permission.
+ */
+#ifndef SOCKS_MEMBLOCK_H_
+#define SOCKS_MEMBLOCK_H_
 
 #include <stddef.h>
 #include <limits.h>
@@ -13,12 +34,106 @@
 			(i)->__idx != ULLONG_MAX; \
 			__next_memory_region(i, type_a, type_b, p_start, p_end))
 
+/* iterate through all memory regions known to memblock.
+
+   this consists of all regions that have been registered
+   with memblock using memblock_add().
+
+   this iteration can be optionally constrained to a given region.
+
+   @param i the iterator. this should be a pointer of type memblock_iter_t.
+            for each iteration, this structure will be filled with details about
+	    the current memory region.
+   @param p_start the lower bound of the memory region to iterate through.
+            if you don't want to use a lower bound, pass 0.
+   @param p_end the upper bound of the memory region to iterate through.
+            if you don't want to use an upper bound, pass UINTPTR_MAX.
+
+   EXAMPLE: to iterate through all memory regions (with no bounds):
+   
+     memblock_iter_t it;
+     for_each_mem_region (&it, 0x0, UINTPTR_MAX) { ... }
+
+
+   EXAMPLE: to iterate through all memory regions between physical
+            addresses 0x40000 and 0x80000:
+
+     memblock_iter_t it;
+     for_each_mem_region (&it, 0x40000, 0x80000) { ... }
+*/
 #define for_each_mem_range(i, p_start, p_end) \
 	__for_each_mem_range(i, &memblock.memory, NULL, p_start, p_end)
 
+/* iterate through all memory regions reserved using memblock.
+
+   this consists of all regions that have been registered
+   with memblock using memblock_reserve().
+
+   this iteration can be optionally constrained to a given region.
+
+   @param i the iterator. this should be a pointer of type memblock_iter_t.
+            for each iteration, this structure will be filled with details about
+	    the current memory region.
+   @param p_start the lower bound of the memory region to iterate through.
+            if you don't want to use a lower bound, pass 0.
+   @param p_end the upper bound of the memory region to iterate through.
+            if you don't want to use an upper bound, pass UINTPTR_MAX.
+
+   EXAMPLE: to iterate through all reserved memory regions (with no bounds):
+   
+     memblock_iter_t it;
+     for_each_reserved_mem_region (&it, 0x0, UINTPTR_MAX) { ... }
+
+
+   EXAMPLE: to iterate through all reserved memory regions between physical
+            addresses 0x40000 and 0x80000:
+
+     memblock_iter_t it;
+     for_each_reserved_mem_region (&it, 0x40000, 0x80000) { ... }
+*/
 #define for_each_reserved_mem_range(i, p_start, p_end) \
 	__for_each_mem_range(i, &memblock.reserved, NULL, p_start, p_end)
 
+/* iterate through all memory regions known by memblock to be free.
+
+   this consists of all regions BETWEEN those regions that have been
+   registered using memblock_reserve(), bounded within the memory
+   regions added using memblock_add().
+
+   this iteration can be optionally constrained to a given region.
+
+   @param i the iterator. this should be a pointer of type memblock_iter_t.
+            for each iteration, this structure will be filled with details about
+	    the current memory region.
+   @param p_start the lower bound of the memory region to iterate through.
+            if you don't want to use a lower bound, pass 0.
+   @param p_end the upper bound of the memory region to iterate through.
+            if you don't want to use an upper bound, pass UINTPTR_MAX.
+
+   EXAMPLE: if you have added the following memory regions to
+   memblock using memblock_add():
+
+     - 0x00000 -> 0x05fff
+     - 0x08000 -> 0x1ffff
+
+   ...and you have reserved the following memory regions using
+   memblock_reserve():
+
+     - 0x01000 -> 0x04fff
+     - 0x09000 -> 0x0ffff
+
+   the following call:
+
+     memblock_iter_t it;
+     for_each_free_mem_range (&it, 0x0, UINTPTR_MAX) { ... }
+
+   would iterate through the following sequence of free memory ranges:
+
+     - 0x00000 -> 0x00fff
+     - 0x05000 -> 0x05fff
+     - 0x08000 -> 0x08fff
+     - 0x10000 -> 0x1ffff
+*/
 #define for_each_free_mem_range(i, p_start, p_end) \
 	__for_each_mem_range(i, &memblock.memory, &memblock.reserved, p_start, p_end)
 
@@ -44,6 +159,8 @@ typedef struct memblock_region {
 	phys_addr_t limit;
 } memblock_region_t;
 
+/* buffer of memblock regions, all of which are the same type
+   (memory, reserved, etc) */
 typedef struct memblock_type {
 	struct memblock_region *regions;
 	unsigned int count;
@@ -71,19 +188,111 @@ typedef struct memblock_iter {
 	memblock_region_status_t it_status;
 } memblock_iter_t;
 
+/* global memblock state. */
 extern memblock_t memblock;
 
 extern int __next_mem_range(memblock_iter_t *it);
 
+/* initialise the global memblock state.
+   this function must be called before any other memblock functions can be used.
+
+   this function sets the bounds of the heap area. memory allocation requests
+   using memblock_alloc() will be constrained to this zone.
+
+   memblock assumes that all physical memory in the system is mapped to
+   an area in virtual memory, such that converting a physical address to
+   a valid virtual address can be done by simply applying an offset.
+
+   @param alloc_start the virtual address of the start of the heap area.
+   @param alloc_end the virtual address of the end of the heap area.
+   @param voffset the offset between the physical address of a given page and
+                  its corresponding virtual address.
+*/
 extern int memblock_init(uintptr_t alloc_start, uintptr_t alloc_end, uintptr_t voffset);
 
+/* add a region of memory to memblock.
+
+   this function is used to define regions of memory that are accessible, but
+   says nothing about the STATE of the given memory.
+
+   all memory is free by default. once a region of memory is added,
+   memblock_reserve() can be used to mark the memory as reserved.
+
+   @param base the physical address of the start of the memory region to add.
+   @oaram size the size of the memory region to add in bytes.
+*/
 extern int memblock_add(phys_addr_t base, size_t size);
+/* mark a region of memory as reserved.
+
+   this function can only operate on regions of memory that have been previously
+   registered with memblock using memblock_add().
+
+   reserved memory will not be used by memblock_alloc(), and will remain
+   reserved when the vm_page memory map is initialised.
+
+   @param base the physical address of the start of the memory region to reserve.
+   @oaram size the size of the memory region to reserve in bytes.
+*/
 extern int memblock_reserve(phys_addr_t base, size_t size);
 
+/* allocate a block of memory, returning a virtual address.
+
+   this function selects the first available region of memory that satisfies
+   the requested allocation size, marks `size` bytes of this region as reserved,
+   and returns the virtual address of the region.
+
+   when looking for a suitable region of memory, this function searches the
+   intersection of the following memory zones:
+     - the regions of memory added with memblock_alloc().
+     - the region of memory specified as the heap bounds during the call
+       to memblock_init().
+   and excludes the following regions:
+     - the regions of memory marked as reserved by memblock_reserve() and
+       previous calls to memblock_alloc()
+
+   @param size the size of the buffer to allocate in bytes.
+*/
 extern void *memblock_alloc(size_t size);
+
+/* allocate a block of memory, returning a physical address.
+
+   this function selects the first available region of memory that satisfies
+   the requested allocation size, marks `size` bytes of this region as reserved,
+   and returns the virtual address of the region.
+
+   when looking for a suitable region of memory, this function searches the
+   intersection of the following memory zones:
+     - the regions of memory added with memblock_alloc().
+     - the region of memory specified as the heap bounds during the call
+       to memblock_init().
+   and excludes the following regions:
+     - the regions of memory marked as reserved by memblock_reserve() and
+       previous calls to memblock_alloc()
+
+   @param size the size of the buffer to allocate in bytes.
+*/
 extern phys_addr_t memblock_alloc_phys(size_t size);
 
+/* free a block of memory using its virtual address.
+
+   due to limitations in memblock (as it is meant to be a simple,
+   early-boot allocator), you must specify the size of the memory
+   region you intend to free.
+
+   @param addr the virtual address of the region to free.
+   @param size the size of the region to free in bytes.
+*/
 extern int memblock_free(void *addr, size_t size);
+
+/* free a block of memory using its physical address.
+
+   due to limitations in memblock (as it is meant to be a simple,
+   early-boot allocator), you must specify the size of the memory
+   region you intend to free.
+
+   @param addr the physical address of the region to free.
+   @param size the size of the region to free in bytes.
+*/
 extern int memblock_free_phys(phys_addr_t addr, size_t size);
 
 extern void __next_memory_region(memblock_iter_t *it, \

sandbox/memblock/memblock.c

@@ -1,3 +1,24 @@
+/*
+  The Clear BSD License
+
+  Copyright (c) 2023 Max Wash
+  All rights reserved.
+
+  Redistribution and use in source and binary forms, with or without
+  modification, are permitted (subject to the limitations in the disclaimer
+  below) provided that the following conditions are met:
+
+  - Redistributions of source code must retain the above copyright notice,
+    this list of conditions and the following disclaimer.
+
+  - Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in the
+    documentation and/or other materials provided with the distribution.
+  
+  - Neither the name of the copyright holder nor the names of its
+    contributors may be used to endorse or promote products derived from this
+    software without specific prior written permission.
+ */
 #include "socks/types.h"
 #include <stdio.h>
 #include <stdbool.h>
@@ -15,8 +36,8 @@
 #define IDX_B(idx) (((idx) >> 32) & 0xFFFFFFFF)
 
 /* the maximum possible value for a pointer type.
- * Note that any pointers returned by the memblock API will still
+   Note that any pointers returned by the memblock API will still
- * be bounded by the defined memory regions, and not by this constant. */
+   be bounded by the defined memory regions, and not by this constant. */
 #define ADDR_MAX (~(uintptr_t)0)
 
 static memblock_region_t init_memory_regions[MEMBLOCK_INIT_MEMORY_REGION_COUNT];
@@ -115,7 +136,7 @@ int memblock_add_range(memblock_type_t *type, uintptr_t base, size_t size, membl
 	memblock_region_t new_region = { .base = base, .limit = limit, .status = status };
 
 	/* two regions with different statuses CANNOT intersect. we first need to check
-	 * to make sure the region being added doesn't violate this rule. */
+	   to make sure the region being added doesn't violate this rule. */
 	for (unsigned int i = 0; i < type->count; i++) {
 		memblock_region_t *cur_region = &type->regions[i];
 
@@ -153,7 +174,7 @@ int memblock_add_range(memblock_type_t *type, uintptr_t base, size_t size, membl
 			memblock_remove_region(type, i);
 
 			/* after memblock_remove_region(), a different region will have moved into the array slot referenced by i.
-			 * decrementing i means we'll stay at the current index and process this region. */
+			   decrementing i means we'll stay at the current index and process this region. */
 			i--;
 			continue;
 		}
@@ -162,9 +183,9 @@ int memblock_add_range(memblock_type_t *type, uintptr_t base, size_t size, membl
 		/* case 4: the region being added meets or partially overlaps a region already in the list. */
 
 		/* there can be an overlap at the beginning and the end of the region being added,
-		 * anything else is either a full overlap (case 3) or not within the region being added at all.
+		   anything else is either a full overlap (case 3) or not within the region being added at all.
-		 * to handle this, remove the region that's already in the list and extend the region being added to cover it.
+		   to handle this, remove the region that's already in the list and extend the region being added to cover it.
-		 * the two regions may overlap and have incompatible statuses, but this case was handled earlier in this function. */
+		   the two regions may overlap and have incompatible statuses, but this case was handled earlier in this function. */
 		if ((new_region.base > cur_region->base || new_region.base == cur_region->limit - 1) && new_region.status == cur_region->status) {
 			/* the new region overlaps the END of the current region, change the base of the new region to match that of the current region. */
 			new_region.base = cur_region->base;
@@ -300,8 +321,8 @@ void __next_memory_region(memblock_iter_t *it, memblock_type_t *type_a, memblock
 			memblock_region_t *r = &type_b->regions[idx_b];
 
 			/* r_start and r_end delimit the region of memory between the current and previous reserved regions.
-			 * if we have gone past the last reserved region, these variables delimit the range between the end
+			   if we have gone past the last reserved region, these variables delimit the range between the end
-			 * of the last reserved region and the end of memory. */
+			   of the last reserved region and the end of memory. */
 			uintptr_t r_start = idx_b > 0 ? r[-1].limit + 1 : 0;
 			uintptr_t r_end;
 
@@ -336,14 +357,14 @@ void __next_memory_region(memblock_iter_t *it, memblock_type_t *type_a, memblock
 			}
 
 			/* we want the area that is overlapped by both
-			 *	region M (m_start - m_end) : The region defined as system memory.
+			  	region M (m_start - m_end) : The region defined as system memory.
-			 *	region R (r_start - r_end) : The region defined as free / outside of any reserved regions.
+			  	region R (r_start - r_end) : The region defined as free / outside of any reserved regions.
 			 */
 			it->it_base = MAX(m_start, r_start);
 			it->it_limit = MIN(m_end, r_end);
 
 			/* further limit the region to the intersection between the region itself and the
-			 * specified iteration bounds */
+			   specified iteration bounds */
 			it->it_base = MAX(it->it_base, start);
 			it->it_limit = MIN(it->it_limit, end);
 
@@ -355,7 +376,7 @@ void __next_memory_region(memblock_iter_t *it, memblock_type_t *type_a, memblock
 			it->it_status = MEMBLOCK_MEMORY;
 
 			/* whichever region is smaller, increment the pointer for that type, so we can
-			 * compare the larger region with the next region of the incremented type. */
+			   compare the larger region with the next region of the incremented type. */
 			if (m_end <= r_end) {
 				idx_a++;
 			} else {