From 1f4f7faebacca75267cc1d63bfeffc30080d017d Mon Sep 17 00:00:00 2001
From: Ciro Santilli <ciro.santilli@gmail.com>
Date: Fri, 4 Aug 2017 08:21:20 +0100
Subject: [PATCH] Document pagemap futher

---
 kernel_module/user/common.h       | 13 ++++++++-----
 kernel_module/user/pagemap_dump.c | 16 +++++++++++++++-
 2 files changed, 23 insertions(+), 6 deletions(-)

diff --git a/kernel_module/user/common.h b/kernel_module/user/common.h
index e76acfb..7c408bf 100644
--- a/kernel_module/user/common.h
+++ b/kernel_module/user/common.h
@@ -7,12 +7,15 @@
 #include <stdlib.h> /* size_t */
 #include <unistd.h> /* pread, sysconf */
 
+/* Format documented at:
+ * https://github.com/torvalds/linux/blob/v4.9/Documentation/vm/pagemap.txt
+ **/
 typedef struct {
-    uint64_t pfn : 54;
-    unsigned int soft_dirty : 1;
-    unsigned int file_page : 1;
-    unsigned int swapped : 1;
-    unsigned int present : 1;
+	uint64_t pfn : 54;
+	unsigned int soft_dirty : 1;
+	unsigned int file_page : 1;
+	unsigned int swapped : 1;
+	unsigned int present : 1;
 } PagemapEntry;
 
 /* Parse the pagemap entry for the given virtual address.
diff --git a/kernel_module/user/pagemap_dump.c b/kernel_module/user/pagemap_dump.c
index ca12717..144a8b3 100644
--- a/kernel_module/user/pagemap_dump.c
+++ b/kernel_module/user/pagemap_dump.c
@@ -9,6 +9,19 @@ Adapted from: https://github.com/dwks/pagemap/blob/8a25747bc79d6080c8b94eac80807
 Dump the page map of a given process PID.
 
 Data sources: /proc/PIC/{map,pagemap}
+
+This program works in two steps:
+
+-   parse the human readable lines lines from `/proc/<pid>/maps`. This files contains lines of form:
+
+        7ffff7b6d000-7ffff7bdd000 r-xp 00000000 fe:00 658                        /lib/libuClibc-1.0.22.so
+
+    which gives us:
+
+    - `7f8af99f8000-7f8af99ff000`: a virtual address range that belong to the process, possibly containing multiple pages.
+    - `/lib/libuClibc-1.0.22.so` the name of the library that owns that memory.
+
+-   loop over each page of each address range, and ask `/proc/<pid>/pagemap` for more information about that page, including the physical address.
 */
 
 #define _XOPEN_SOURCE 700
@@ -22,7 +35,8 @@ Data sources: /proc/PIC/{map,pagemap}
 
 #include "common.h" /* pagemap_get_entry */
 
-int main(int argc, char **argv) {
+int main(int argc, char **argv)
+{
 	char buffer[BUFSIZ];
 	char maps_file[BUFSIZ];
 	char pagemap_file[BUFSIZ];