kernel/arch: Add documentation for several paging functions

diff --git a/kernel/arch/paging.c b/kernel/arch/paging.c
index 1274e942ca53fe4171aa8b57d2336200a77880fc..15d61535b1fe3823de1f19f195f13c8132843b9e 100644 (file)
--- a/kernel/arch/paging.c
+++ b/kernel/arch/paging.c
@@ -755,13 +755,35 @@ void* pg_init(struct multiboot_info *info)
        return((void*)(cr3 | _pg_flags));
 }
 
+/*
+ * pg_dir_get_kstack() - Get the address of a page directory's kernel-mode stack
+ *
+ * SYNOPSIS
+ *  void *pg_dir_get_kstack(struct pagedir *pgdir);
+ *
+ * DESCRIPTION
+ *  The pg_dir_get_kstack() function looks up the kernel-mode stack that is mapped into
+ *  the page directory pointed to by `pgdir' and returns the linear address of that stack.
+ *  This is done by iterating over all regions that are associated with the page directory,
+ *  looking for the region whose type is REGION_TYPE_KSTACK. If no such region can be found,
+ *  NULL is returned instead.
+ *
+ * RETURN VALUE
+ *  This function will return the linear address of the kernel-mode stack of the page
+ *  directory, or NULL if no kernel-mode stack is mapped into the page directory.
+ *
+ * ERRORS
+ *  This function does not provide further information in case of an error.
+ */
 void* pg_dir_get_kstack(struct pagedir *pgdir)
 {
        struct region *reg;
        void *ret_val;
        int i;
 
-       for(ret_val = NULL, i = 0; i < CONFIG_PAGING_DIR_MAXREGIONS; i++) {
+       ret_val = NULL;
+
+       for(i = 0; i < CONFIG_PAGING_DIR_MAXREGIONS; i++) {
                reg = pgdir->pd_regions[i];
 
                if(reg->reg_type == REGION_TYPE_KSTACK) {
@@ -784,13 +806,35 @@ void* pg_dir_get_kstack(struct pagedir *pgdir)
        return(ret_val);
 }
 
+/*
+ * pg_dir_get_ustack() - Get the virtual address of a page directory's user-mode stack
+ *
+ * SYNOPSIS
+ *  void *pg_dir_get_ustack(struct pagedir *pgdir);
+ *
+ * DESCRIPTION
+ *  The pg_dir_get_ustack() function looks up the user-mode stack that is mapped into the
+ *  page directory pointed to by `pgdir' and returns the virtual address of that stack.
+ *  This is achieved by iterating over all regions that are associated with the page
+ *  directory, looking for the region with type REGION_TYPE_STACK. If no such region could
+ *  be found, NULL is returned instead.
+ *
+ * RETURN VALUE
+ *  Upon success, the virtual address of the user-mode stack of the page directory is
+ *  returned. Otherwise NULL is returned.
+ *
+ * ERRORS
+ *  This function does not provide further information in case of an error.
+ */
 void* pg_dir_get_ustack(struct pagedir *pgdir)
 {
        struct region *reg;
        void *ret_val;
        int i;
 
-       for(ret_val = NULL, i = 0; i < CONFIG_PAGING_DIR_MAXREGIONS; i++) {
+       ret_val = NULL;
+
+       for(i = 0; i < CONFIG_PAGING_DIR_MAXREGIONS; i++) {
                reg = pgdir->pd_regions[i];
 
                if(reg->reg_type == REGION_TYPE_STACK) {
@@ -802,13 +846,37 @@ void* pg_dir_get_ustack(struct pagedir *pgdir)
        return(ret_val);
 }
 
+/*
+ * pg_dir_get_ustack_top() - Get the top of a page directory's user-mode stack
+ *
+ * SYNOPSIS
+ *  void *pg_dir_get_ustack_top(struct pagedir *pgdir);
+ *
+ * DESCRIPTION
+ *  The pg_dir_get_ustack_top() function looks up the user-mode stack that is mapped
+ *  into the page directory pointed to by `pgdir' and returns the virtual address that
+ *  is behind that stack (i.e. stack_base + stack_size). This is achieved by iterating
+ *  over all regions that are associated with the page directory, looking for the
+ *  region with type REGION_TYPE_STACK. If no such region could be found, NULL is
+ *  returned in its stead.
+ *
+ * RETURN VALUE
+ *  Upon success, this function returns the address that is right behind the end of
+ *  the user-mode stack of the page directory. If there is no user-mode stack mapped
+ *  into the page directory, NULL is returned instead.
+ *
+ * ERRORS
+ *  This function does not provide additional information in case of an error.
+ */
 void* pg_dir_get_ustack_top(struct pagedir *pgdir)
 {
        struct region *reg;
        void *ret_val;
        int i;
 
-       for(ret_val = NULL, i = 0; i < CONFIG_PAGING_DIR_MAXREGIONS; i++) {
+       ret_val = NULL;
+
+       for(i = 0; i < CONFIG_PAGING_DIR_MAXREGIONS; i++) {
                reg = pgdir->pd_regions[i];
 
                if(reg->reg_type == REGION_TYPE_STACK) {
@@ -820,6 +888,28 @@ void* pg_dir_get_ustack_top(struct pagedir *pgdir)
        return(ret_val);
 }
 
+/*
+ * pg_dir_grow_ustack() - Increase the size of a page directory's user-mode stack
+ *
+ * SYNOPSIS
+ *  int pg_dir_grow_ustack(struct pagedir *pgdir, void *new_bottom);
+ *
+ * DESCRIPTION
+ *  The pg_dir_grow_ustack() function locates the bottom of the user-mode stack that is
+ *  mapped into the page directory pointed to by `pgdir' and attempts to map pages in
+ *  order to fill in the region between the bottom of the stack and the location pointed
+ *  to by `new_bottom'. Pages that are added to the stack will be added with the same
+ *  page attributes as the rest of the stack. If the location pointed to by `new_bottom'
+ *  is not lower than the current bottom of the stack nothing will be done. This function
+ *  will not increase the stack size beyond the limit defined by CONFIG_USER_STACK_LIMIT.
+ *
+ * RETURN VALUE
+ *  On success, zero is returned. Otherwise, a negative error number will be returned.
+ *
+ * ERRORS
+ *  -EBADFD There is no stack mapped into the page directory
+ *  -ENOMEM There is not enough memory available to grow the stack
+ */
 int pg_dir_grow_ustack(struct pagedir *pgdir, void *new_bottom)
 {
        struct region *stack;