[PATCH v2] maple tree: Add some comments

[PATCH v2] maple tree: Add some comments

[Dev Jain]

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.

Signed-off-by: Dev Jain <dev.jain@arm.com>
---

v1->v2:
 - Drop MAPLE_ROOT_NODE comment modification

v1:
 - https://lore.kernel.org/all/20250626171918.17261-2-dev.jain@arm.com/

 include/linux/maple_tree.h | 4 ++--
 lib/maple_tree.c           | 8 +++++++-
 2 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/include/linux/maple_tree.h b/include/linux/maple_tree.h
index 9ef129038224..bafe143b1f78 100644
--- 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 0e85e92c5375..b4ee2d29d7a9 100644
--- 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;
-- 
2.30.2

Re: [PATCH v2] maple tree: Add some comments

[Liam R. Howlett]

* Dev Jain <dev.jain@arm.com> [250703 02:33]:
> 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.
> 
> Signed-off-by: Dev Jain <dev.jain@arm.com>

Thanks!

Reviewed-by: Liam R. Howlett <Liam.Howlett@oracle.com>


> ---
> 
> v1->v2:
>  - Drop MAPLE_ROOT_NODE comment modification
> 
> v1:
>  - https://lore.kernel.org/all/20250626171918.17261-2-dev.jain@arm.com/
> 
>  include/linux/maple_tree.h | 4 ++--
>  lib/maple_tree.c           | 8 +++++++-
>  2 files changed, 9 insertions(+), 3 deletions(-)
> 
> diff --git a/include/linux/maple_tree.h b/include/linux/maple_tree.h
> index 9ef129038224..bafe143b1f78 100644
> --- 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 0e85e92c5375..b4ee2d29d7a9 100644
> --- 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;
> -- 
> 2.30.2
> 
> 
> -- 
> maple-tree mailing list
> maple-tree@lists.infradead.org
> https://lists.infradead.org/mailman/listinfo/maple-tree