allocator(9) and framer(9): add pages

2 files changed, 117 insertions, 0 deletions

diff --git a/mem/docs/allocator.9.scd b/mem/docs/allocator.9.scd
new file mode 100644
index 0000000..df708a7
--- /dev/null
+++ b/mem/docs/allocator.9.scd
@@ -0,0 +1,68 @@
+MEMALLOCATOR(9)
+
+# NAME
+
+*mem_alloc*, *mem_realloc*, *mem_free* - allocator interface
+
+# SYNOPSIS
+
+```
+#include <mem/allocator.h>
+
+typedef struct mem_allocator MemAllocator;
+
+void *mem_alloc(MemAllocator *self, usize n);
+void *mem_realloc(MemAllocator *self, void *ptr, usize n);
+void mem_free(MemAllocator *self, void *ptr);
+```
+
+# DESCRIPTION
+
+An allocator is an abstract structure capable of managing several regions of memory in such a way that allocated regions to not impinge on each other. These regions may also be freed - meaning that the allocator will try to make them available again for allocation, so as to avoid running out of memory if proper care is taken - and reallocated - changing the size of an allocated region.
+
+*MemAllocator* defines the basic interface common to all allocators in the kernel, comprising of the 3 following operations:
+
+	. allocation (*mem_alloc()*)
+	. reallocation (*mem_realloc()*)
+	. freeing (*mem_free()*)
+
+Actual implementations of the allocator use this structure as a virtual dispatch table in order to dispatch these procedure calls to their according implementations, such as *MemFramer*.
+
+When working with allocators, proper care must be taken in regards of the limitations of each implementations of the allocator. For example, some allocators may be limited in terms of allocated region sizes; while others may not support one or more of those 3 operations.
+
+## Allocating
+
+The *mem_alloc()* function is used to dispatch the allocation method call to the underlying implementation of the allocator. This function takes the following arguments:
+
+	_self_	The allocator that should be used
+	_n_	The minimal amount of char-sized units of memory the allocated region should span
+
+## Reallocation
+
+The *mem_realloc()* function is used to dispatch the reallocation method call to the underlying implemention of the allocator. Reallocation consists in modifying the size of a previously allocated region. *mem_realloc()* takes the following arguments:
+
+	_self_	The allocator that should be used
+	_ptr_	The previously allocated region of memory, as returned by a previous call to *mem_alloc()* or *mem_realloc()*
+	_n_	The new size of the allocated region, in char-sized units
+
+## Freeing
+
+The *mem_free()* function is used to dispatch the free method call to the underlying imprlemention of the allocator. Freeing consists in indicating to the allocator that a region is no longer in use and that it can be reclaimed; this reclaimed memory could then, for example, be used as the result of other allocation requests by *mem_alloc()* or *mem_realloc()*. *mem_free()* takes the following arguments:
+
+	_self_	The allocator that should be used
+	_ptr_	The previously allocated region of memory, as returned by a previous call to *mem_alloc()* or *mem_realloc()*
+
+Proper care should be taken to only free region of memory that have been allocated by a previous call to the same allocator, this includes double frees.
+
+# RETURN VALUES
+
+*mem_alloc()* returns the beginning of the allocated region on success, nil on error or 0 provided.
+*mem_realloc()* returns the beginning of the reallocated region on success, nil on error or 0 provided. Note: in case nil, the passed region is freed.
+
+# CODE REFERENCES
+
+The MemAllocator interface and its dispatching functions are implemented in _mem/allocator.c_.
+
+# SEE ALSO
+
+memframer(9)
\ No newline at end of file
diff --git a/mem/docs/framer.9.scd b/mem/docs/framer.9.scd
new file mode 100644
index 0000000..5836e19
--- /dev/null
+++ b/mem/docs/framer.9.scd
@@ -0,0 +1,49 @@
+MEMFRAMER(9)
+
+# NAME
+
+*mem_framer_install*, *mem_framer_alloc*, *mem_framer_free* - allocator for fixed and aligned frames
+
+# SYNOPSIS
+
+```
+#include <mem/framer.h>
+
+typedef struct mem_framer MemFramer;
+
+MemFramer *mem_framer_install(void *addr, usize end, uint blksz);
+void *mem_framer_alloc(MemAllocator *self, usize n);
+void mem_framer_free(MemAllocator *self, void *ptr);
+```
+
+# DESCRIPTION
+
+*MemFramer* and its related functions is an implementation of memallocator(9) designed to manage the allocation and freeing of chunks of same size - they are called _frames_ - that are boundary aligned on multiples of that size.
+
+*MemFramer* is a linked-list allocator, meaning that when a frame is requested, it can either pop the frame from a free list (a linked list of frames that have previously been freed), or bump a new frame from the region of usable memory that it manages.
+
+## Installing
+
+A *MemFramer* can be installed in a particular region of usable memory to manage it using *mem_framer_install()*. It accepts the following arguments:
+
+	_addr_	The address at which the *MemFramer* will be installed
+	_end_	The address marking the end of the region of usable memory that has to be managed
+	_blksz_	The size of each individual frame
+
+## Allocating
+
+Allocation can be done using *mem_framer_alloc()*. This method is the implementation of mem_alloc(9) for a *MemFramer*.
+
+Note: allocating more than the frame size leads to an allocation failure.
+
+## Freeing
+
+Freeing of a frame can be done using *mem_framer_free()*. Refer to mem_free(9) for the documentation.
+
+# CODE REFERENCES
+
+The *MemFramer* allocator and its related functions are defined in _mem/framer.c_.
+
+# SEE ALSO
+
+memallocator(9)
\ No newline at end of file