maple_tree: Add layout comments to header.

Signed-off-by: Liam R. Howlett <Liam.Howlett@Oracle.com>

diff --git a/include/linux/maple_tree.h b/include/linux/maple_tree.h
index 9e5956511cf83403c0e9071ca5f27af803a3d91f..ff2bfb7ed318ec3bcd628297cf5ca0d3e2ffd0ff 100644 (file)
--- a/include/linux/maple_tree.h
+++ b/include/linux/maple_tree.h
@@ -43,9 +43,42 @@
 
 typedef struct maple_enode *maple_enode; // encoded node.
 typedef struct maple_pnode *maple_pnode; // parent node.
-/*
- * We can be more cache-efficient if we interleave pivots and slots.
- * Code will be more complex, though.
+
+
+/**
+ * maple_tree node explained
+ *
+ * Each node type has a number of slots for entries and a number of slots for
+ * pivots.  In the case of dense nodes, the pivots are implied by the position
+ * and are simply the slot index + the minimum of the node.
+ *
+ * In regular B-Tree terms, pivots are called keys.  The term pivot is used to
+ * indicate that the tree is specifying ranges,  Pivots may appear in the
+ * subtree with an entry attached to the value where as keys are unique to a
+ * specific position of a B-tree.  Pivot values are inclusive of the slot with
+ * the same index.
+ *
+ *
+ * The following illustrates the layout of a range64 nodes slots and pivots.
+ *
+ *           _________________________________
+ *  Slots -> | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
+ *           ┬   ┬   ┬   ┬   ┬   ┬   ┬   ┬   ┬
+ *           │   │   │   │   │   │   │   │   └─ Implied maximum
+ *           │   │   │   │   │   │   │   └─ Pivot 6
+ *           │   │   │   │   │   │   └─ Pivot 5
+ *           │   │   │   │   │   └─ Pivot 4
+ *           │   │   │   │   └─ Pivot 3
+ *           │   │   │   └─ Pivot 2
+ *           │   │   └─ Pivot 1
+ *           │   └─ Pivot 0
+ *           └─  Implied minimum
+ *
+ * Slot contents:
+ *  Internal (non-leaf) nodes contain pointers to other nodes.
+ *  Leaf nodes contain entries.
+ *
+ *
  */
 struct maple_range_64 {
        struct maple_pnode *parent;