[doc] Add spec for vmalloc, add file headers

include/sys/attr.h

@@ -1,3 +1,8 @@
+/** vim: set ft=cpp.doxygen :
+ * @file sys/attr.h
+ * @brief Storage/function attributes for clarification or
+ *        compiler hints
+ */
 #pragma once
 
 #define __weak __attribute__((weak))

include/sys/debug.h

@@ -1,3 +1,7 @@
+/** vim: set ft=cpp.doxygen :
+ * @file sys/debug.h
+ * @brief Kernel debug output functions
+ */
 #pragma once
 #include <stdarg.h>
 #include <stdint.h>

include/sys/heap.h

@@ -1,5 +1,7 @@
-// vim: set ft=cpp.doxygen :
-// Platform-generic kernel heap header
+/** vim: set ft=cpp.doxygen :
+ * @file sys/heap.h
+ * @brief Kernel heap memory managament functions
+ */
 #pragma once
 #include <sys/types.h>
 

include/sys/mem.h

@@ -1,3 +1,7 @@
+/** vim: set ft=cpp.doxygen :
+ * @file sys/mem.h
+ * @brief Generic memory operations
+ */
 #pragma once
 #include <stdint.h>
 #include <stddef.h>

include/sys/mm.h

@@ -1,4 +1,7 @@
-/* vim: set ft=cpp.doxygen : */
+/** vim: set ft=cpp.doxygen :
+ * @file sys/mm.h
+ * @brief Virtual memory space management functions
+ */
 #pragma once
 #include <stddef.h>
 #include <stdint.h>

include/sys/panic.h

@@ -1,3 +1,7 @@
+/** vim: set ft=cpp.doxygen :
+ * @file sys/panic.h
+ * @brief Kernel assertion-testing and critical failure functions
+ */
 #pragma once
 #include <stdarg.h>
 #include <stdint.h>

include/sys/string.h

@@ -1,3 +1,7 @@
+/** vim: set ft=cpp.doxygen :
+ * @file sys/string.h
+ * @brief Generic string operations
+ */
 #pragma once
 #include <stddef.h>
 

include/sys/vmalloc.h

@@ -0,0 +1,44 @@
+// vim: set ft=cpp.doxygen :
+/**
+ * @file sys/vmalloc.h
+ * @brief Contiguous virtual memory range management functions
+ */
+#pragma once
+#include "sys/mm.h"
+
+/**
+ * @brief Find a free contiguous memory range inside a given one
+ *        in a virtual memory space.
+ * @param pd Virtual memory space
+ * @param from Start of the range to allocate from
+ * @param to End of the range to allocate from
+ * @param npages Size of the needed range in 4K pages
+ * @return Address of the resulting range on success,
+ *         MM_NADDR if such range cannot be allocated
+ */
+uintptr_t vmfind(mm_space_t pd, uintptr_t from, uintptr_t to, size_t npages);
+
+/**
+ * @brief Allocate a contiguous virtual memory range in a space
+ *        within `from'..`to' limits and map it to a set of
+ *        physical pages (which may not be contiguous).
+ * @param pd Virtual memory space
+ * @param from Start of the range to allocate from
+ * @param to End of the range to allocate from
+ * @param npages Count of 4K pages to allocate
+ * @param flags:
+ *        * VM_ALLOC_USER - The range is available for userspace
+ *        * VM_ALLOC_WRITE - The range is writable
+ * @return Virtual address of the resulting range on success,
+ *         MM_NADDR otherwise
+ */
+uintptr_t vmalloc(mm_space_t pd, uintptr_t from, uintptr_t to, size_t npages, int flags);
+
+/**
+ * @brief Deallocate a virtual memory range and physical pages
+ *        it's mapped to.
+ * @param pd Virtual memory space
+ * @param addr Address of the beginning of the range
+ * @param npages Size of the range in 4K pages
+ */
+void vmfree(mm_space_t pd, uintptr_t addr, size_t npages);