maple tree: add some comments

Add comments explaining the fields for maple_metadata, since "end" is
ambiguous and "gap" can be confused as the largest gap, whereas it is
actually the offset of the largest gap.

Add comment for mas_ascend() to explain, whose min and max we are trying
to find.  Explain that, for example, if we are already on offset zero,
then the parent min is mas->min, otherwise we need to walk up to find the
implied pivot min.

Link: https://lkml.kernel.org/r/20250703063338.51509-1-dev.jain@arm.com
Signed-off-by: Dev Jain <dev.jain@arm.com>
Reviewed-by: Liam R. Howlett <Liam.Howlett@oracle.com>
Cc: Wei Yang <richard.weiyang@gmail.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>

diff --git a/include/linux/maple_tree.h b/include/linux/maple_tree.h
index 9ef1290382249462d73ae72435dada7ce4b0622c..bafe143b1f783202e27b32567fffee4149e8e266 100644 (file)
--- a/include/linux/maple_tree.h
+++ b/include/linux/maple_tree.h
@@ -75,8 +75,8 @@
  * searching for gaps or any other code that needs to find the end of the data.
  */
 struct maple_metadata {
-       unsigned char end;
-       unsigned char gap;
+       unsigned char end;      /* end of data */
+       unsigned char gap;      /* offset of largest gap */
 };
 
 /*

diff --git a/lib/maple_tree.c b/lib/maple_tree.c
index 0e85e92c5375b74faf6caaa6a8581b0181f5b118..b4ee2d29d7a962ca374467d0533185f2db3d35ff 100644 (file)
--- a/lib/maple_tree.c
+++ b/lib/maple_tree.c
@@ -1053,7 +1053,7 @@ static inline void mte_set_gap(const struct maple_enode *mn,
  * mas_ascend() - Walk up a level of the tree.
  * @mas: The maple state
  *
- * Sets the @mas->max and @mas->min to the correct values when walking up.  This
+ * Sets the @mas->max and @mas->min for the parent node of mas->node.  This
  * may cause several levels of walking up to find the correct min and max.
  * May find a dead node which will cause a premature return.
  * Return: 1 on dead node, 0 otherwise
@@ -1098,6 +1098,12 @@ static int mas_ascend(struct ma_state *mas)
 
        min = 0;
        max = ULONG_MAX;
+
+       /*
+        * !mas->offset implies that parent node min == mas->min.
+        * mas->offset > 0 implies that we need to walk up to find the
+        * implied pivot min.
+        */
        if (!mas->offset) {
                min = mas->min;
                set_min = true;