From ddab13b829e8a8d9fdb6e5e38bc6c3af688c48f1 Mon Sep 17 00:00:00 2001
From: Ali Mashtizadeh <mashti@uwaterloo.ca>
Date: Sun, 10 Sep 2023 16:31:44 -0400
Subject: [PATCH] pmap

---
 sys/amd64/pmap.c | 140 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 140 insertions(+)

diff --git a/sys/amd64/pmap.c b/sys/amd64/pmap.c
index 07ed38d..9cf7a84 100644
--- a/sys/amd64/pmap.c
+++ b/sys/amd64/pmap.c
@@ -69,6 +69,13 @@ PMap_InitAP()
     PMap_LoadAS(&systemAS);
 }
 
+/**
+ * PMap_NewAS --
+ *
+ * Create a new address space.
+ *
+ * @return Newly created address space.
+ */
 AS*
 PMap_NewAS()
 {
@@ -98,6 +105,13 @@ PMap_NewAS()
     return as;
 }
 
+/**
+ * PMap_DestroyAS --
+ *
+ * Destroys an address space and releases the physical pages.
+ *
+ * @param [in] space Address space to destroy.
+ */
 void
 PMap_DestroyAS(AS *space)
 {
@@ -143,12 +157,27 @@ PMap_DestroyAS(AS *space)
     PAlloc_Release(space);
 }
 
+/**
+ * PMap_CurrentAS --
+ *
+ * Get the current address space on this CPU.
+ *
+ * @return Current address space.
+ */
 AS *
 PMap_CurrentAS()
 {
     return currentAS[THISCPU()];
 }
 
+/**
+ * PMap_LoadAS --
+ *
+ * Load an address space into the CPU.  Reloads the CR3 register in x86-64 that 
+ * points the physical page tables and flushes the TLB entries.
+ *
+ * @param [in] space Address space to load.
+ */
 void
 PMap_LoadAS(AS *space)
 {
@@ -156,6 +185,13 @@ PMap_LoadAS(AS *space)
     currentAS[THISCPU()] = space;
 }
 
+/**
+ * PMapAllocPageTable --
+ *
+ * Allocates and initializes a page table.
+ *
+ * @return Newly created PageTable.
+ */
 static PageTable *
 PMapAllocPageTable()
 {
@@ -172,6 +208,14 @@ PMapAllocPageTable()
     return pgtbl;
 }
 
+/**
+ * PMap_Translate --
+ *
+ * Translates a virtual address to physical address for a given address space.
+ *
+ * @param [in] space Address space we wish to lookup a mapping in.
+ * @param [in] va Virtual address we wish to translate.
+ */
 uintptr_t
 PMap_Translate(AS *space, uintptr_t va)
 {
@@ -218,6 +262,18 @@ PMap_Translate(AS *space, uintptr_t va)
     return (*entry & ~(PGMASK | PTE_NX)) + (va & PGMASK);
 }
 
+/**
+ * PMapLookupEntry --
+ *
+ * Lookup a virtual address in a page table and return a pointer to the page 
+ * entry.  This function allocates page tables as necessary to fill in the 
+ * 4-level heirarchy.
+ *
+ * @param [in] space Address space to search.
+ * @param [in] va Virtual address to lookup.
+ * @param [out] entry Pointer will point to the PageEntry.
+ * @param [in] size Page size we want to use.
+ */
 static void
 PMapLookupEntry(AS *space, uint64_t va, PageEntry **entry, int size)
 {
@@ -281,6 +337,20 @@ PMapLookupEntry(AS *space, uint64_t va, PageEntry **entry, int size)
     return;
 }
 
+/**
+ * PMap_Map --
+ *
+ * Map a physical to virtual mapping in an address space.
+ *
+ * @param [in] as Address space.
+ * @param [in] phys Physical address.
+ * @param [in] virt Virtual address.
+ * @param [in] pages Pages to map in.
+ * @param [in] flags Flags to apply to the mapping.
+ *
+ * @retval true On success
+ * @retval false On failure
+ */
 bool
 PMap_Map(AS *as, uint64_t phys, uint64_t virt, uint64_t pages, uint64_t flags)
 {
@@ -301,6 +371,18 @@ PMap_Map(AS *as, uint64_t phys, uint64_t virt, uint64_t pages, uint64_t flags)
     return true;
 }
 
+/**
+ * PMap_Unmap --
+ *
+ * Unmap a range of addresses.
+ *
+ * @param [in] as Address space.
+ * @param [in] va Virtual address.
+ * @param [in] pages Pages to map in.
+ *
+ * @retval true On success
+ * @retval false On failure
+ */
 bool
 PMap_Unmap(AS *as, uint64_t va, uint64_t pages)
 {
@@ -323,6 +405,20 @@ PMap_Unmap(AS *as, uint64_t va, uint64_t pages)
     return true;
 }
 
+/**
+ * PMap_AllocMap --
+ *
+ * Map a virtual mapping in an address space and back it by newly allocated 
+ * memory.
+ *
+ * @param [in] as Address space.
+ * @param [in] virt Virtual address.
+ * @param [in] pages Pages to map in.
+ * @param [in] flags Flags to apply to the mapping.
+ *
+ * @retval true On success
+ * @retval false On failure
+ */
 bool
 PMap_AllocMap(AS *as, uint64_t virt, uint64_t len, uint64_t flags)
 {
@@ -349,12 +445,37 @@ PMap_AllocMap(AS *as, uint64_t virt, uint64_t len, uint64_t flags)
     return true;
 }
 
+/**
+ * PMap_SystemLookup --
+ *
+ * Lookup a kernel virtual address in a page table and return a pointer to the 
+ * page entry.  This function allocates page tables as necessary to fill in the 
+ * 4-level heirarchy.
+ *
+ * @param [in] va Virtual address to lookup.
+ * @param [out] entry Pointer will point to the PageEntry.
+ * @param [in] size Page size we want to use.
+ */
 void
 PMap_SystemLookup(uint64_t va, PageEntry **entry, int size)
 {
     PMapLookupEntry(&systemAS, va, entry, size);
 }
 
+/**
+ * PMap_SystemLMap --
+ *
+ * Map a range of large (2MB) physical pages to virtual pages in the kernel 
+ * address space that is shared by all processes.
+ *
+ * @param [in] phys Physical address.
+ * @param [in] virt Virtual address.
+ * @param [in] lpages Large pages to map in.
+ * @param [in] flags Flags to apply to the mapping.
+ *
+ * @retval true On success
+ * @retval false On failure
+ */
 bool
 PMap_SystemLMap(uint64_t phys, uint64_t virt, uint64_t lpages, uint64_t flags)
 {
@@ -375,6 +496,20 @@ PMap_SystemLMap(uint64_t phys, uint64_t virt, uint64_t lpages, uint64_t flags)
     return true;
 }
 
+/**
+ * PMap_SystemLMap --
+ *
+ * Map a range of physical pages to virtual pages in the kernel address space 
+ * that is shared by all processes.
+ *
+ * @param [in] phys Physical address.
+ * @param [in] virt Virtual address.
+ * @param [in] pages Pages to map in.
+ * @param [in] flags Flags to apply to the mapping.
+ *
+ * @retval true On success
+ * @retval false On failure
+ */
 bool
 PMap_SystemMap(uint64_t phys, uint64_t virt, uint64_t pages, uint64_t flags)
 {
@@ -395,6 +530,11 @@ PMap_SystemMap(uint64_t phys, uint64_t virt, uint64_t pages, uint64_t flags)
     return true;
 }
 
+/**
+ * PMap_SystemUnmap --
+ *
+ * We do not currently use this!
+ */
 bool
 PMap_SystemUnmap(uint64_t virt, uint64_t pages)
 {