From 43f50be659df78447bfb0bdb1c0d6751b014a760 Mon Sep 17 00:00:00 2001
From: "Liam R. Howlett" <Liam.Howlett@Oracle.com>
Date: Mon, 18 Jan 2021 14:19:42 -0500
Subject: [PATCH] maple_tree: Comments and drop a function.

Add some more comments

Signed-off-by: Liam R. Howlett <Liam.Howlett@Oracle.com>
---
 lib/maple_tree.c | 68 ++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 54 insertions(+), 14 deletions(-)

diff --git a/lib/maple_tree.c b/lib/maple_tree.c
index 927047b1c70f..86624da32c8c 100644
--- a/lib/maple_tree.c
+++ b/lib/maple_tree.c
@@ -95,7 +95,6 @@ static inline int mt_alloc_bulk(gfp_t gfp, size_t size, void **nodes)
 				     nodes);
 }
 
-
 static inline void mt_free_bulk(size_t size, void **nodes)
 {
 	kmem_cache_free_bulk(maple_node_cache, size, nodes);
@@ -108,6 +107,13 @@ static void mt_free_rcu(struct rcu_head *head)
 	kmem_cache_free(maple_node_cache, node);
 }
 
+/* ma_free_rcu() - Use rcu callback to free a maple node
+ * node: The node to free
+ *
+ * The maple tree uses the parent pointer to indicate this node is no longer in
+ * use and will be freed.
+ * Internal only.
+ */
 static void ma_free_rcu(struct maple_node *node)
 {
 	node->parent = ma_parent_ptr(node);
@@ -199,26 +205,32 @@ static inline struct maple_node *mte_to_node(const struct maple_enode *entry)
 	return (struct maple_node *)((unsigned long)entry & ~127);
 }
 
+/* mte_to_mat() - Convert a maple encoded node to a maple topiary node.
+ * @entry: The maple encoded node
+ * Returns a maple topiary pointer
+ */
 static inline struct maple_topiary *mte_to_mat(const struct maple_enode *entry)
 {
 	return (struct maple_topiary *)((unsigned long)entry & ~127);
 }
 
+/* mas_mn() - Get the maple state node.
+ * @mas: The maple state
+ * Returns the maple node (not encoded - bare pointer).
+ */
 static inline struct maple_node *mas_mn(const struct ma_state *mas)
 {
 	return mte_to_node(mas->node);
 }
 
+/* mte_set_node_dead() - Set a maple encoded node as dead.
+ * @mn: The maple encoded node.
+ */
 static inline void mte_set_node_dead(struct maple_enode *mn)
 {
 	mte_to_node(mn)->parent = ma_parent_ptr(mte_to_node(mn));
 }
 
-static inline void mte_free(struct maple_enode *enode)
-{
-	ma_free_rcu(mte_to_node(enode));
-}
-
 static inline struct maple_enode *mt_mk_node(const struct maple_node *node,
 		enum maple_type type) {
 	return (void *)((unsigned long)node | (type << 3) | 4);
@@ -962,7 +974,7 @@ nomem:
 static inline void mas_free(struct ma_state *mas, struct maple_enode *used)
 {
 	if (mt_in_rcu(mas->tree))
-		mte_free(used);
+		ma_free_rcu(mte_to_node(used));
 	else
 		mas_push_node(mas, used);
 }
@@ -3663,7 +3675,13 @@ no_entry:
 }
 
 /*
- * prev node entry
+ * mas_prev_nentry() - Get the previous node entry.
+ * @mas: The maple state.
+ * @limit: The lower limit to check for a value.
+ *
+ * Returns the entry, NULL otherwise.
+ *
+ * Internal only.
  */
 static inline void *mas_prev_nentry(struct ma_state *mas, unsigned long limit)
 {
@@ -3703,6 +3721,8 @@ static inline void *mas_prev_nentry(struct ma_state *mas, unsigned long limit)
  * mas_next_nentry() - Next node entry.  Set the @mas slot to the next valid
  * entry and range_start to the start value for that entry.  If there is no
  * entry, returns false.
+ *
+ * Internal only.
  */
 static inline void *mas_next_nentry(struct ma_state *mas, unsigned long max,
 		unsigned long *range_start)
@@ -3762,9 +3782,13 @@ found:
 }
 
 /*
- *  _mas_walk(): A walk that supports returning the range in which an
- *  index is located.
+ *  _mas_walk() - Walk to @mas->index and set the range values.
+ * @mas: The maple state.
+ * @*range_min: The minimum range to be set.
+ * @*range_max: The maximum range to be set.
+ * Returns: True if a value exists, false otherwise.
  *
+ * Ranges are only valid if there is a valid entry at @mas->index.
  */
 static inline bool _mas_walk(struct ma_state *mas, unsigned long *range_min,
 			     unsigned long *range_max)
@@ -3948,9 +3972,12 @@ next_node:
 }
 
 /*
+ * _mas_prev() - Return the previous entry
+ * @mas: The maple state.
+ * @limit: The lower limit to check.
+ * Returns the previous entry or NULL.
  *
- * _mas_prev() - Find the previous entry from the current ma state.
- * @mas the current maple state (must have a valid slot)
+ * Internal only.
  */
 static inline void *_mas_prev(struct ma_state *mas, unsigned long limit)
 {
@@ -3976,9 +4003,14 @@ retry:
 }
 
 /*
- * mas_prev() - Get the previous entry.  Can return the zero entry.
- *
+ * mas_prev() - Get the previous entry
+ * @mas: The maple state
+ * @min: The minimum value to check.
+ * Returns the previous value or NULL.
  *
+ * Will reset mas to MAS_START if the node is MAS_NONE.  Will stop on not
+ * searchable nodes.  If mas->node is MAS_START, it will first look up the
+ * index, then get the previous entry.
  */
 void *mas_prev(struct ma_state *mas, unsigned long min)
 {
@@ -4162,6 +4194,13 @@ done:
 	return found;
 }
 
+/* mas_walk() - Search for @mas->index in the tree.
+ * @mas - the maple state.
+ * Returns the entry at the location or NULL.
+ *
+ * mas->index and mas->last will be set to the range if there is a value.  If
+ * mas->node is MAS_NONE, reset to MAS_START.
+ */
 void *mas_walk(struct ma_state *mas)
 {
 	unsigned long range_min, range_max;
@@ -4703,6 +4742,7 @@ void *mas_next(struct ma_state *mas, unsigned long max)
 	return _mas_next(mas, max);
 }
 EXPORT_SYMBOL_GPL(mas_next);
+
 /*
  * mas_erase() - Find the range in which index resides and erase the entire
  * range.
-- 
2.50.1