From: Matthias Kruk Date: Sat, 1 Aug 2020 13:37:22 +0000 (+0900) Subject: kernel/arch: Add documentation for several paging functions X-Git-Url: https://git.corax.cc/?a=commitdiff_plain;h=a4042591ebaa2c971010ecb57792d1db3d063032;p=corax kernel/arch: Add documentation for several paging functions --- diff --git a/kernel/arch/paging.c b/kernel/arch/paging.c index 1274e94..15d6153 100644 --- 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;