diff --git a/sandbox/memblock/include/socks/memblock.h b/sandbox/memblock/include/socks/memblock.h index f5856d0..37df045 100644 --- a/sandbox/memblock/include/socks/memblock.h +++ b/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 #include @@ -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, \ diff --git a/sandbox/memblock/memblock.c b/sandbox/memblock/memblock.c index 3d045c6..4cc7256 100644 --- a/sandbox/memblock/memblock.c +++ b/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 #include @@ -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 - * be bounded by the defined memory regions, and not by this constant. */ + Note that any pointers returned by the memblock API will still + 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. - * 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. */ + 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. + 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 - * of the last reserved region and the end of memory. */ + 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. */ 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 R (r_start - r_end) : The region defined as free / outside of any reserved regions. + 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. */ 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 {