Added a doxyfile and documented arch/x86/include/asm/page.h

.gitignore

@@ -5,3 +5,11 @@
 *.sym
 *.pcap
 *.img
+tags
+tools/make_initrd
+newlib/examples/hello
+newlib/examples/echo
+newlib/tmp/*
+newlib/x86/*
+metalsvm.elf
+documentation/html

arch/x86/include/asm/page.h

@@ -17,8 +17,12 @@
  * This file is part of MetalSVM.
  */
 
-/*
- * Defines the interface for and structures relating to paging.
+/**
+ * @file arch/x86/include/asm/page.h
+ * @brief Definitions and functions related to paging
+ * @author Stefan Lankes
+ *
+ * This file defines the interface for paging as like structures related to paging.
  */
 
 #ifndef __ARCH_PAGE_H__
@@ -58,64 +62,144 @@
 #define KERN_PAGE	(PG_PRESENT|PG_RW|PG_GLOBAL)
 #define USER_PAGE	(PG_PRESENT|PG_RW|PG_USER)
  
+/** @brief Page table structure
+ *
+ * This structure keeps page table entries.\n
+ * A page table consists of 1024 entries.
+ */
 typedef struct page_table
 {
+	/// Page table entries are unsigned 32bit integers.
 	uint32_t entries[1024];
 } page_table_t __attribute__ ((aligned (4096)));
 
+/** @brief Page directory structure
+ *
+ * This structure keeps page directory entries.\
+ * A page directory consists of 1024 entries.
+ */
 typedef struct page_dir
 {
+	/// Page dir entries are unsigned 32bit integers.
 	uint32_t entries[1024];
 } page_dir_t __attribute__ ((aligned (4096)));
 
-/*
- * Converts a virtual address to a physical
+/** @brief Converts a virtual address to a physical
+ *
+ * @param viraddr Virtual address to convert
+ * @return physical address
  */
-size_t virt_to_phys(size_t);
+size_t virt_to_phys(size_t viraddr);
 
-/*
- * Allocates an virtual address space range of npages
+/** @brief Allocates a virtual address space range of npages
+ *
+ * The address range with special flags (if given) will have the size of n pages.
+ *
+ * @param npages The range in page-granularity
+ * @param flags further page flags
+ *
+ * @return The new range's address
  */
 size_t vm_alloc(uint32_t npages, uint32_t flags);
 
-/*
- * Frees a range in the virtual address space
+/** @brief Frees a range in the virtual address space
+ *
+ * @param addr Address of the range
+ * @param npages Size of the range in pages
+ *
+ * @return
+ * - 0 on success
+ * - -EINVAL (-22) on failure.
  */
 int vm_free(size_t addr, uint32_t npages);
 
-/*
- * Unmap the physical memory at a specific virtual address
+/** @brief Unmap the physical memory at a specific virtual address
+ *
+ * All Page table entries within this range will be marked as not present
+ * and (in the case of userspace memory) the page usage of the task will be decremented.
+ *
+ * @param viraddr The range's virtual address
+ * @param npages The range's size in pages
+ *
+ * @return
+ * - 0 on success
+ * - -EINVAL (-22) on failure.
  */
 int unmap_region(size_t viraddr, uint32_t npages);
 
-/*
- * Maps a physical memory region at a specific virtual address.
+/** @brief Mapping a physical mem-region to a virtual address
+ *
+ * Maps a physical memory region to a specific virtual address.
  * If the virtual address is zero, this functions allocates a valid virtual address on demand.
+ *
+ * @param viraddr Desired virtual address
+ * @param phyaddr Physical address to map from
+ * @param npages The Region's size in pages
+ * @param flags Further page flags
+ *
+ * @return
+ * - A virtual address on success
+ * - 0 on failure.
  */
-size_t map_region(size_t viraddr, size_t phyaddr, uint32_t pages, uint32_t type);
+size_t map_region(size_t viraddr, size_t phyaddr, uint32_t npages, uint32_t flags);
 
-/*
- * Sets up the environment and enables paging.
+/** @brief Sets up the environment and enables paging.
+ *
+ * - Installs the page handler IRQ
+ * - sets up the whole page directory and page tables for the kernel space (virt adr = phys adr)
+ * - maps VGA, multi boot info and initrd into kernel space
+ * - writes to cr0 and cr3 register
+ * - marks 'paging_enabled' var = 1
+ * - Registers kernel thread for task state switching
+ *
+ * @return returns
+ * - 0 on success
+ * - -ENOMEM (-12) on failure
  */
 int arch_paging_init(void);
 
-/*
- * Returns the page directory of the boot task
+/** @brief Returns the page directory of the boot task
+ *
+ * The boot task's page directory is a static array of page_dir_t type vars.
+ *
+ * @return Returns the address of the boot task's page dir array.
  */
 page_dir_t* get_boot_pgd(void);
 
-/*
- * Setup a new page directory for a new user-level task
+/** @brief Setup a new page directory for a new user-level task
+ *
+ * @param task Pointer to the task-specific task_t structure
+ * @param copy If true: PGD will be a copy of the kernel's address space PGD
+ *
+ * @return
+ * - counter of allocated page tables
+ * - -ENOMEM (-12) on failure
  */
 int create_pgd(task_t* task, int copy);
 
-/*
- * Delete page directory and its page tables
+/** @brief Delete page directory and its page tables
+ *
+ * Puts page tables and page directory back to buffer and
+ * sets the task's page directory pointer to NULL
+ *
+ * @return
+ * - 0 on success
+ * - -EINVAL (-22) on failure (in case PGD is still the boot-pgd).
  */
 int drop_pgd(void);
 
-/*
- * Change the page permission in the page tables of the current task
+/** @brief Change the page permission in the page tables of the current task
+ *
+ * Applies given flags noted in the 'flags' parameter to
+ * the range denoted by virtual start and end addresses.
+ *
+ * @param start Range's virtual start address
+ * @param end Range's virtual end address
+ * @param flags flags to apply
+ *
+ * @return
+ * - 0 on success
+ * - -EINVAL (-22) on failure.
  */
 int change_page_permissions(size_t start, size_t end, uint32_t flags);
 

arch/x86/mm/page.c

@@ -35,10 +35,10 @@
  * Virtual Memory Layout of the standard configuration
  * (1 GB kernel space)
  *
- * 0x00000000 - 0x000FFFFF: reserved for IO devices
- * 0x00100000 - 0x0DEADFFF: Kernel (size depends on the configuration)
- * 0x0DEAE000 - 0x3FFFEFFF: Kernel heap
- * 0x3FFFF000 - 0x3FFFFFFF: Page Tables are mapped in this region
+ * 0x00000000 - 0x000FFFFF: reserved for IO devices (16MB)
+ * 0x00100000 - 0x0DEADFFF: Kernel (size depends on the configuration) (221MB)
+ * 0x0DEAE000 - 0x3FFFEFFF: Kernel heap (801MB)
+ * 0x3FFFF000 - 0x3FFFFFFF: Page Tables are mapped in this region (4KB)
  *			   (The last 256 entries belongs to kernel space)
  */
 
@@ -62,7 +62,7 @@ page_dir_t* get_boot_pgd(void)
 /*
  * TODO: We create a full copy of the current task. Copy-On-Access will be the better solution.
  *
- * No PGD locking is needed because onls creat_pgd use this function and holds already the
+ * No PGD locking is needed because onls create_pgd use this function and holds already the
  * PGD lock.
  */
 inline static size_t copy_page_table(task_t* task, uint32_t pgd_index, page_table_t* pgt, int* counter)