From e870960655bb4fec6d740dc6da91d05825491e24 Mon Sep 17 00:00:00 2001
From: Nathaniel Filardo <nwf20@cl.cam.ac.uk>
Date: Mon, 25 Nov 2019 15:01:53 +0000
Subject: [PATCH] Some minor chunkmap commentary

---
 src/mem/chunkmap.h | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/src/mem/chunkmap.h b/src/mem/chunkmap.h
index 5306fea..1a9504f 100644
--- a/src/mem/chunkmap.h
+++ b/src/mem/chunkmap.h
@@ -15,8 +15,34 @@ namespace snmalloc
     CMNotOurs = 0,
     CMSuperslab = 1,
     CMMediumslab = 2
+
+    /*
+     * Values 3 (inclusive) through SUPERSLAB_BITS (exclusive) are as yet
+     * unused.
+     *
+     * Values SUPERSLAB_BITS (inclusive) through 64 (exclusive, as it would
+     * represent the entire address space) are used for log2(size) at the
+     * heads of large allocations.  See SuperslabMap::set_large_size.
+     *
+     * Values 64 (inclusive) through 128 (exclusive) are used for entries
+     * within a large allocation.  A value of x at pagemap entry p indicates
+     * that there are at least 2^(x-64) (inclusive) and at most 2^(x+1-64)
+     * (exclusive) page map entries between p and the start of the
+     * allocation.  See SuperslabMap::set_large_size and external_address's
+     * handling of large reallocation redirections.
+     *
+     * Values 128 (inclusive) through 255 (inclusive) are as yet unused.
+     */
+
   };
 
+  /*
+   * Ensure that ChunkMapSuperslabKind values are actually disjoint, i.e.,
+   * that large allocations don't land on CMMediumslab.
+   */
+  static_assert(
+    SUPERSLAB_BITS > CMMediumslab, "Large allocations may be too small");
+
 #ifndef SNMALLOC_MAX_FLATPAGEMAP_SIZE
 // Use flat map is under a single node.
 #  define SNMALLOC_MAX_FLATPAGEMAP_SIZE PAGEMAP_NODE_SIZE
@@ -120,6 +146,9 @@ namespace snmalloc
   {
     /**
      * Get the pagemap entry corresponding to a specific address.
+     *
+     * Despite the type, the return value is an enum ChunkMapSuperslabKind
+     * or one of the reserved values described therewith.
      */
     static uint8_t get(address_t p)
     {