Fix an off-by-one error in V2 reverse page table lookups

This would occationally manifest as an inability to find the runlist
page in BAR2, as only part of the page table was being traversed.

Also includes non-functional changes to documentation, scoping, and
structure layout.

1 files changed, 46 insertions, 11 deletions

diff --git a/nvdebug.h b/nvdebug.h
index 39b2e6e..fcc6cff 100644
--- a/nvdebug.h
+++ b/nvdebug.h
@@ -856,13 +856,46 @@ typedef union {
         uint64_t raw;
 } page_dir_config_t;
 
-/* Page directory entry
-
-  Note: Format changed with Pascal (how?)
-
-  Support: Pascal, Volta, Turing, Ampere, Ada
+/* NVIDIA GMMU (GPU Memory Management Unit) uses page tables that are mostly
+  straight-forward starting with Pascal ("page table version 2"), except for a
+  few quirks (like 16-byte PDE0 entries, but all other entries are 8 bytes).
+
+  All you really need to know is that any given Page Directory Entry (PDE)
+  contains a pointer to the start of a 4k page densely filled with PDEs or Page
+  Table Entries (PTEs).
+
+  == Page Table Refresher ==
+  Page tables convert virtual addresses to physical addresses, and they do this
+  via a tree structure. Leafs (PTEs) contain a physical address, and the path
+  from root to leaf is defined by the virtual address. Non-leaf nodes are PDEs.
+  When decending, the virtual address is sliced into pieces, and one slice is
+  used at each level (as an index) to select the next-visited node (in level+1).
+
+  V2 of NVIDIA's page table format uses 4 levels of PDEs and a final level of
+  PTEs. How the virtual address is sliced to yield an index into each level and
+  a page offset is shown by Fig 1.
+
+  == Figure 1 ==
+  Page Offset (12 bits) <---------------------------------------+
+  Page Table Entry (PTE) (9 bits) <--------------------+        |
+  Page Directory Entry (PDE) 0 (8 bits) <-----+        |        |
+  PDE1 (9 bits) <--------------------+        |        |        |
+  PDE2 (9 bits) <-----------+        |        |        |        |
+  PDE3 (2 bits) <--+        |        |        |        |        |
+                   ^        ^        ^        ^        ^        ^
+  Virtual addr: [48, 47] [46, 38] [37, 29] [28, 21] [20, 12] [11, 0]
+
+  The following arrays merely represent different projections of Fig. 1, and
+  only one is strictly needed to reconstruct all the others. However, due to
+  the complexity of page tables, we include all of these to aid in readability.
 */
-// FIXME: PDE/PTEs are actually 64 bits =S
+// How many nodes/entries per level in V2 of NVIDIA's page table format
+static const int NV_MMU_PT_V2_SZ[5] = {4, 512, 512, 256, 512};
+// Size in bytes of an entry at a particular level
+static const int NV_MMU_PT_V2_ENTRY_SZ[5] = {8, 8, 8, 16, 8};
+// Which bit index is the least significant in indexing each page level
+static const int NV_MMU_PT_V2_LSB[5] = {47, 38, 29, 21, 12};
+
 // Important: Aperture keys are different with PDEs
 enum PD_TARGET {
         PD_AND_TARGET_INVALID = 0,  // b000
@@ -894,25 +927,27 @@ static inline const char *pd_target_to_text(enum PD_TARGET t) {
         }
 }
 
-// PDE/PTE V2 type
+// Page Directory Entry/Page Table Entry V2 type
 // Note: As the meaning of target (bits 2:1) changes depending on if the entry
 //       is a PTE or not, this combines them into a single target field to
 //       simplify comparisons.
 // Support: Pascal, Volta, Turing, Ampere, Ada
 //
 // V3 introduced with Hopper, but Hopper and Blackwell also support V2
+//
+// FIXME: This structure is 32 bits, but PDE/PTEs are actually 64 bits!
 typedef union {
         // Page Directory Entry (PDE)
         struct {
-                bool is_pte:1;
-                 uint32_t __target:2;
+                enum PD_TARGET target:3;
                 bool is_volatile:1;
                  uint32_t padding1:4;
                 uint32_t addr:24;
         } __attribute__((packed));
         // Page Table Entry (PTE)
         struct {
-                enum PD_TARGET target:3;
+                bool is_pte:1;
+                enum INST_TARGET aperture:2;
                  uint32_t __is_volatile:1;
                 bool is_encrypted:1;
                 bool is_privileged:1;
@@ -923,7 +958,7 @@ typedef union {
         uint32_t raw;
 } page_dir_entry_t;
 
-// PDE/PTE V1 types
+// Page Directory Entry/Page Table Entry V1 type
 // Support: Fermi, Kepler, Maxwell
 enum V1_PD_TARGET {
         PD_TARGET_INVALID = 0,