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

1 files changed, 49 insertions, 0 deletions

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