[persistent-data, dm-array] Comments and rename some methods

dm_setup_array_info -> dm_array_info_init
dm_array_get -> dm_array_get_value
dm_array_set -> dm_array_set_value

drivers/md/dm-cache-metadata.c

@@ -229,10 +229,10 @@ static void __setup_mapping_info(struct dm_cache_metadata *cmd)
 	vt.inc = NULL;
 	vt.dec = NULL;
 	vt.equal = NULL;
-	dm_setup_array_info(&cmd->info, cmd->tm, &vt);
+	dm_array_info_init(&cmd->info, cmd->tm, &vt);
 
 	vt.size = sizeof(__le32);
-	dm_setup_array_info(&cmd->hint_info, cmd->tm, &vt);
+	dm_array_info_init(&cmd->hint_info, cmd->tm, &vt);
 }
 
 static int __write_initial_superblock(struct dm_cache_metadata *cmd)
@@ -789,8 +789,8 @@ static int __remove(struct dm_cache_metadata *cmd, dm_cblock_t cblock)
 	__le64 value = pack_value(0, 0);
 
 	__dm_bless_for_disk(&value);
-	r = dm_array_set(&cmd->info, cmd->root, from_cblock(cblock),
-			 &value, &cmd->root);
+	r = dm_array_set_value(&cmd->info, cmd->root, from_cblock(cblock),
+			       &value, &cmd->root);
 	if (r)
 		return r;
 
@@ -816,8 +816,8 @@ static int __insert(struct dm_cache_metadata *cmd,
 	__le64 value = pack_value(oblock, M_VALID);
 	__dm_bless_for_disk(&value);
 
-	r = dm_array_set(&cmd->info, cmd->root, from_cblock(cblock),
-			 &value, &cmd->root);
+	r = dm_array_set_value(&cmd->info, cmd->root, from_cblock(cblock),
+			       &value, &cmd->root);
 	if (r)
 		return r;
 
@@ -871,8 +871,8 @@ static int __load_mapping(void *context, uint64_t cblock, void *leaf)
 
 	if (flags & M_VALID) {
 		if (thunk->hints_valid) {
-			r = dm_array_get(&cmd->hint_info, cmd->hint_root,
-					 cblock, &hint_value);
+			r = dm_array_get_value(&cmd->hint_info, cmd->hint_root,
+					       cblock, &hint_value);
 			if (r && r != -ENODATA)
 				return r;
 		}
@@ -960,7 +960,7 @@ static int __dirty(struct dm_cache_metadata *cmd, dm_cblock_t cblock, bool dirty
 	dm_oblock_t oblock;
 	__le64 value;
 
-	r = dm_array_get(&cmd->info, cmd->root, from_cblock(cblock), &value);
+	r = dm_array_get_value(&cmd->info, cmd->root, from_cblock(cblock), &value);
 	if (r)
 		return r;
 
@@ -973,8 +973,8 @@ static int __dirty(struct dm_cache_metadata *cmd, dm_cblock_t cblock, bool dirty
 	value = pack_value(oblock, flags | (dirty ? M_DIRTY : 0));
 	__dm_bless_for_disk(&value);
 
-	r = dm_array_set(&cmd->info, cmd->root, from_cblock(cblock),
-			 &value, &cmd->root);
+	r = dm_array_set_value(&cmd->info, cmd->root, from_cblock(cblock),
+			       &value, &cmd->root);
 	if (r)
 		return r;
 
@@ -1107,8 +1107,8 @@ static int save_hint(struct dm_cache_metadata *cmd, dm_cblock_t cblock,
 	__le32 value = cpu_to_le32(hint);
 	__dm_bless_for_disk(&value);
 
-	r = dm_array_set(&cmd->hint_info, cmd->hint_root,
-			 from_cblock(cblock), &value, &cmd->hint_root);
+	r = dm_array_set_value(&cmd->hint_info, cmd->hint_root,
+			       from_cblock(cblock), &value, &cmd->hint_root);
 	cmd->changed = true;
 
 	return r;

drivers/md/persistent-data/dm-array.c

@@ -613,9 +613,9 @@ static int block_equal(void *context, const void *value1, const void *value2)
 
 /*----------------------------------------------------------------*/
 
-void dm_setup_array_info(struct dm_array_info *info,
-			 struct dm_transaction_manager *tm,
-			 struct dm_btree_value_type *vt)
+void dm_array_info_init(struct dm_array_info *info,
+			struct dm_transaction_manager *tm,
+			struct dm_btree_value_type *vt)
 {
 	struct dm_btree_value_type *bvt = &info->btree_info.value_type;
 
@@ -629,7 +629,7 @@ void dm_setup_array_info(struct dm_array_info *info,
 	bvt->dec = block_dec;
 	bvt->equal = block_equal;
 }
-EXPORT_SYMBOL_GPL(dm_setup_array_info);
+EXPORT_SYMBOL_GPL(dm_array_info_init);
 
 int dm_array_empty(struct dm_array_info *info, dm_block_t *root)
 {
@@ -684,8 +684,8 @@ int dm_array_del(struct dm_array_info *info, dm_block_t root)
 }
 EXPORT_SYMBOL_GPL(dm_array_del);
 
-int dm_array_get(struct dm_array_info *info, dm_block_t root,
-		 uint32_t index, void *value_le)
+int dm_array_get_value(struct dm_array_info *info, dm_block_t root,
+		       uint32_t index, void *value_le)
 {
 	int r;
 	struct dm_block *block;
@@ -710,10 +710,10 @@ int dm_array_get(struct dm_array_info *info, dm_block_t root,
 	unlock_ablock(info, block);
 	return r;
 }
-EXPORT_SYMBOL_GPL(dm_array_get);
+EXPORT_SYMBOL_GPL(dm_array_get_value);
 
-static int array_set(struct dm_array_info *info, dm_block_t root,
-		     uint32_t index, const void *value, dm_block_t *new_root)
+static int array_set_value(struct dm_array_info *info, dm_block_t root,
+			   uint32_t index, const void *value, dm_block_t *new_root)
 {
 	int r;
 	struct dm_block *block;
@@ -753,17 +753,17 @@ static int array_set(struct dm_array_info *info, dm_block_t root,
 	return r;
 }
 
-int dm_array_set(struct dm_array_info *info, dm_block_t root,
+int dm_array_set_value(struct dm_array_info *info, dm_block_t root,
 		 uint32_t index, const void *value, dm_block_t *new_root)
 		 __dm_written_to_disk(value)
 {
 	int r;
 
-	r = array_set(info, root, index, value, new_root);
+	r = array_set_value(info, root, index, value, new_root);
 	__dm_unbless_for_disk(value);
 	return r;
 }
-EXPORT_SYMBOL_GPL(dm_array_set);
+EXPORT_SYMBOL_GPL(dm_array_set_value);
 
 struct walk_info {
 	struct dm_array_info *info;

drivers/md/persistent-data/dm-array.h

@@ -13,21 +13,57 @@
 /*
  * The dm-array is a persistent version of an array.  It packs the data
  * more efficiently than a btree which will result in less disk space use,
- * and a performance boost.  The get and set operations are still O(ln(n)),
- * but with a much smaller constant.
+ * and a performance boost.  The element get and set operations are still
+ * O(ln(n)), but with a much smaller constant.
  *
  * The value type structure is reused from the btree type to support proper
  * reference counting of values.
  *
  * The arrays implicitly know their length, and bounds are checked for
- * lookups and updates.  It doesn't store this in an accessible place
+ * lookups and updated.  It doesn't store this in an accessible place
  * because it would waste a whole metadata block.  Make sure you store the
  * size along with the array root in your encompassing data.
+ *
+ * Array entries are indexed via an unsigned integer starting from zero.
+ * Arrays are not sparse; if you resize an array to have 'n' entries then
+ * 'n - 1' will be the last valid index.
+ *
+ * Typical use:
+ *
+ * a) initialise a dm_array_info structure.  This describes the array
+ *    values and ties it into a specific transaction manager.  It holds no
+ *    instance data; the same info can be used for many similar arrays if
+ *    you wish.
+ *
+ * b) Get yourself a root.  The root is the index of a block of data on the
+ *    disk that holds a particular instance of an array.  You may have a
+ *    pre existing root in your metadata that you wish to use, or you may
+ *    want to create a brand new, empty array with dm_array_empty().
+ *
+ * Like the other data structures in this library, dm_array objects are
+ * immutable between transactions.  Update functions will return you the
+ * root for a _new_ array.  If you've incremented the old root, via
+ * dm_tm_inc(), before calling the update function you may continue to use
+ * it in parallel with the new root.
+ *
+ * c) resize an array with dm_array_resize().
+ *
+ * d) Get a value from the array with dm_array_get_value().
+ *
+ * e) Set a value in the array with dm_array_set_value().
+ *
+ * f) Walk an array of values in index order with dm_array_walk().  More
+ *    efficient than making many calls to dm_array_get_value().
+ *
+ * g) Destroy the array with dm_array_del().  This tells the transaction
+ *    manager that you're no longer using this data structure so it can
+ *    recycle it's blocks.  (dm_array_dec() would be a better name for it,
+ *    but del is in keeping with dm_btree_del()).
  */
 
 /*
  * Describes an array.  Don't initialise this structure yourself, use the
- * setup function below.
+ * init function below.
  */
 struct dm_array_info {
 	struct dm_transaction_manager *tm;
@@ -36,18 +72,19 @@ struct dm_array_info {
 };
 
 /*
- * Sets up a dm_array_info structure.
+ * Sets up a dm_array_info structure.  You don't need to do anything with
+ * this structure when you finish using it.
  *
  * info - the structure being filled in.
  * tm   - the transaction manager that should supervise this structure.
  * vt   - describes the leaf values.
  */
-void dm_setup_array_info(struct dm_array_info *info,
-			 struct dm_transaction_manager *tm,
-			 struct dm_btree_value_type *vt);
+void dm_array_info_init(struct dm_array_info *info,
+			struct dm_transaction_manager *tm,
+			struct dm_btree_value_type *vt);
 
 /*
- * Initialise an empty array, zero length array.
+ * Create an empty, zero length array.
  *
  * info - describes the array
  * root - on success this will be filled out with the root block
@@ -59,12 +96,13 @@ int dm_array_empty(struct dm_array_info *info, dm_block_t *root);
  *
  * info - describes the array
  * root - the root block of the array on disk
- * old_size - yes, the caller is responsible for remembering the size of the array
+ * old_size - the caller is responsible for remembering the size of
+ *            the array
  * new_size - can be bigger or smaller than old_size
  * value - if we're growing the array the new entries will have this value
  * new_root - on success, points to the new root block
  *
- * If growing the inc function for value will be called the appropriate
+ * If growing the inc function for 'value' will be called the appropriate
  * number of times.  So if the caller is holding a reference they may want
  * to drop it.
  */
@@ -85,30 +123,30 @@ int dm_array_del(struct dm_array_info *info, dm_block_t root);
  * info - describes the array
  * root - root block of the array
  * index - array index
- * value - the value to be read.  Will be in on disk format of course.
+ * value - the value to be read.  Will be in on-disk format of course.
  *
  * -ENODATA will be returned if the index is out of bounds.
  */
-int dm_array_get(struct dm_array_info *info, dm_block_t root,
-		 uint32_t index, void *value);
+int dm_array_get_value(struct dm_array_info *info, dm_block_t root,
+		       uint32_t index, void *value);
 
 /*
  * Set an entry in the array.
  *
  * info - describes the array
  * root - root block of the array
  * index - array index
- * value - value to be written to disk.  Make sure you bless this before
- *         calling.
+ * value - value to be written to disk.  Make sure you confirm the value is
+ *         in on-disk format with__dm_bless_for_disk() before calling.
  * new_root - the new root block
  *
  * The old value being overwritten will be decremented, the new value
  * incremented.
  *
  * -ENODATA will be returned if the index is out of bounds.
  */
-int dm_array_set(struct dm_array_info *info, dm_block_t root,
-		 uint32_t index, const void *value, dm_block_t *new_root)
+int dm_array_set_value(struct dm_array_info *info, dm_block_t root,
+		       uint32_t index, const void *value, dm_block_t *new_root)
 	__dm_written_to_disk(value);
 
 /*
@@ -120,7 +158,7 @@ int dm_array_set(struct dm_array_info *info, dm_block_t root,
  * context - passed to the callback
  */
 int dm_array_walk(struct dm_array_info *info, dm_block_t root,
-		  int (*fn)(void *, uint64_t key, void *leaf),
+		  int (*fn)(void *context, uint64_t key, void *leaf),
 		  void *context);
 
 /*----------------------------------------------------------------*/

drivers/md/persistent-data/dm-bitset.c

@@ -28,7 +28,7 @@ static struct dm_btree_value_type bitset_bvt = {
 void dm_bitset_info_init(struct dm_transaction_manager *tm,
 			 struct dm_bitset_info *info)
 {
-	dm_setup_array_info(&info->array_info, tm, &bitset_bvt);
+	dm_array_info_init(&info->array_info, tm, &bitset_bvt);
 	info->current_index_set = false;
 }
 EXPORT_SYMBOL_GPL(dm_bitset_info_init);
@@ -71,8 +71,8 @@ int dm_bitset_flush(struct dm_bitset_info *info, dm_block_t root,
 	value = cpu_to_le64(info->current_bits);
 
 	__dm_bless_for_disk(&value);
-	r = dm_array_set(&info->array_info, root, info->current_index,
-			 &value, new_root);
+	r = dm_array_set_value(&info->array_info, root, info->current_index,
+			       &value, new_root);
 	if (r)
 		return r;
 
@@ -87,7 +87,7 @@ static int read_bits(struct dm_bitset_info *info, dm_block_t root,
 	int r;
 	__le64 value;
 
-	r = dm_array_get(&info->array_info, root, array_index, &value);
+	r = dm_array_get_value(&info->array_info, root, array_index, &value);
 	if (r)
 		return r;