Btrfs: Commenting/cleanup

Signed-off-by: Chris Mason <chris.mason@oracle.com>

fs/btrfs/ctree.c

@@ -20,6 +20,11 @@ static void release_path(struct ctree_root *root, struct ctree_path *p)
 	}
 }
 
+/*
+ * The leaf data grows from end-to-front in the node.
+ * this returns the address of the start of the last item,
+ * which is the stop of the leaf data stack
+ */
 static inline unsigned int leaf_data_end(struct leaf *leaf)
 {
 	unsigned int nr = leaf->header.nritems;
@@ -28,6 +33,11 @@ static inline unsigned int leaf_data_end(struct leaf *leaf)
 	return leaf->items[nr-1].offset;
 }
 
+/*
+ * The space between the end of the leaf items and
+ * the start of the leaf data.  IOW, how much room
+ * the leaf has left for both items and data
+ */
 static inline int leaf_free_space(struct leaf *leaf)
 {
 	int data_end = leaf_data_end(leaf);
@@ -36,6 +46,9 @@ static inline int leaf_free_space(struct leaf *leaf)
 	return (char *)(leaf->data + data_end) - (char *)items_end;
 }
 
+/*
+ * compare two keys in a memcmp fashion
+ */
 int comp_keys(struct key *k1, struct key *k2)
 {
 	if (k1->objectid > k2->objectid)
@@ -52,6 +65,16 @@ int comp_keys(struct key *k1, struct key *k2)
 		return -1;
 	return 0;
 }
+
+/*
+ * search for key in the array p.  items p are item_size apart
+ * and there are 'max' items in p
+ * the slot in the array is returned via slot, and it points to
+ * the place where you would insert key if it is not found in
+ * the array.
+ *
+ * slot may point to max if the key is bigger than all of the keys
+ */
 int generic_bin_search(char *p, int item_size, struct key *key,
 		       int max, int *slot)
 {
@@ -92,6 +115,14 @@ int bin_search(struct node *c, struct key *key, int *slot)
 	return -1;
 }
 
+/*
+ * look for key in the tree.  path is filled in with nodes along the way
+ * if key is found, we return zero and you can find the item in the leaf
+ * level of the path (level 0)
+ *
+ * If the key isn't found, the path points to the slot where it should
+ * be inserted.
+ */
 int search_slot(struct ctree_root *root, struct key *key, struct ctree_path *p)
 {
 	struct tree_buffer *b = root->node;
@@ -120,12 +151,18 @@ int search_slot(struct ctree_root *root, struct key *key, struct ctree_path *p)
 	return -1;
 }
 
+/*
+ * adjust the pointers going up the tree, starting at level
+ * making sure the right key of each node is points to 'key'.
+ * This is used after shifting pointers to the left, so it stops
+ * fixing up pointers when a given leaf/node is not in slot 0 of the
+ * higher levels
+ */
 static void fixup_low_keys(struct ctree_root *root,
 			   struct ctree_path *path, struct key *key,
 			   int level)
 {
 	int i;
-	/* adjust the pointers going up the tree */
 	for (i = level; i < MAX_LEVEL; i++) {
 		struct node *t;
 		int tslot = path->slots[i];
@@ -139,64 +176,16 @@ static void fixup_low_keys(struct ctree_root *root,
 	}
 }
 
-int __insert_ptr(struct ctree_root *root,
+/*
-		struct ctree_path *path, struct key *key,
+ * try to push data from one node into the next node left in the
-		u64 blocknr, int slot, int level)
+ * tree.  The src node is found at specified level in the path.
-{
+ * If some bytes were pushed, return 0, otherwise return 1.
-	struct node *c;
+ *
-	struct node *lower;
+ * Lower nodes/leaves in the path are not touched, higher nodes may
-	struct key *lower_key;
+ * be modified to reflect the push.
-	int nritems;
+ *
-	/* need a new root */
+ * The path is altered to reflect the push.
-	if (!path->nodes[level]) {
+ */
-		struct tree_buffer *t;
-		t = alloc_free_block(root);
-		c = &t->node;
-		memset(c, 0, sizeof(c));
-		c->header.nritems = 2;
-		c->header.flags = node_level(level);
-		c->header.blocknr = t->blocknr;
-		lower = &path->nodes[level-1]->node;
-		if (is_leaf(lower->header.flags))
-			lower_key = &((struct leaf *)lower)->items[0].key;
-		else
-			lower_key = lower->keys;
-		memcpy(c->keys, lower_key, sizeof(struct key));
-		memcpy(c->keys + 1, key, sizeof(struct key));
-		c->blockptrs[0] = path->nodes[level-1]->blocknr;
-		c->blockptrs[1] = blocknr;
-		/* the path has an extra ref to root->node */
-		tree_block_release(root, root->node);
-		root->node = t;
-		t->count++;
-		write_tree_block(root, t);
-		path->nodes[level] = t;
-		path->slots[level] = 0;
-		if (c->keys[1].objectid == 0)
-			BUG();
-		return 0;
-	}
-	lower = &path->nodes[level]->node;
-	nritems = lower->header.nritems;
-	if (slot > nritems)
-		BUG();
-	if (nritems == NODEPTRS_PER_BLOCK)
-		BUG();
-	if (slot != nritems) {
-		memmove(lower->keys + slot + 1, lower->keys + slot,
-			(nritems - slot) * sizeof(struct key));
-		memmove(lower->blockptrs + slot + 1, lower->blockptrs + slot,
-			(nritems - slot) * sizeof(u64));
-	}
-	memcpy(lower->keys + slot, key, sizeof(struct key));
-	lower->blockptrs[slot] = blocknr;
-	lower->header.nritems++;
-	if (lower->keys[1].objectid == 0)
-			BUG();
-	write_tree_block(root, path->nodes[level]);
-	return 0;
-}
-
 int push_node_left(struct ctree_root *root, struct ctree_path *path, int level)
 {
 	int slot;
@@ -259,6 +248,16 @@ int push_node_left(struct ctree_root *root, struct ctree_path *path, int level)
 	return 0;
 }
 
+/*
+ * try to push data from one node into the next node right in the
+ * tree.  The src node is found at specified level in the path.
+ * If some bytes were pushed, return 0, otherwise return 1.
+ *
+ * Lower nodes/leaves in the path are not touched, higher nodes may
+ * be modified to reflect the push.
+ *
+ * The path is altered to reflect the push.
+ */
 int push_node_right(struct ctree_root *root, struct ctree_path *path, int level)
 {
 	int slot;
@@ -270,8 +269,11 @@ int push_node_right(struct ctree_root *root, struct ctree_path *path, int level)
 	int dst_nritems;
 	int src_nritems;
 
+	/* can't push from the root */
 	if (level == MAX_LEVEL - 1 || path->nodes[level + 1] == 0)
 		return 1;
+
+	/* only try to push inside the node higher up */
 	slot = path->slots[level + 1];
 	if (slot == NODEPTRS_PER_BLOCK - 1)
 		return 1;
@@ -315,7 +317,7 @@ int push_node_right(struct ctree_root *root, struct ctree_path *path, int level)
 	write_tree_block(root, t);
 	write_tree_block(root, src_buffer);
 
-	/* then fixup the leaf pointer in the path */
+	/* then fixup the pointers in the path */
 	if (path->slots[level] >= src->header.nritems) {
 		path->slots[level] -= src->header.nritems;
 		tree_block_release(root, path->nodes[level]);
@@ -327,6 +329,76 @@ int push_node_right(struct ctree_root *root, struct ctree_path *path, int level)
 	return 0;
 }
 
+/*
+ * worker function to insert a single pointer in a node.
+ * the node should have enough room for the pointer already
+ * slot and level indicate where you want the key to go, and
+ * blocknr is the block the key points to.
+ */
+int __insert_ptr(struct ctree_root *root,
+		struct ctree_path *path, struct key *key,
+		u64 blocknr, int slot, int level)
+{
+	struct node *c;
+	struct node *lower;
+	struct key *lower_key;
+	int nritems;
+	/* need a new root */
+	if (!path->nodes[level]) {
+		struct tree_buffer *t;
+		t = alloc_free_block(root);
+		c = &t->node;
+		memset(c, 0, sizeof(c));
+		c->header.nritems = 2;
+		c->header.flags = node_level(level);
+		c->header.blocknr = t->blocknr;
+		lower = &path->nodes[level-1]->node;
+		if (is_leaf(lower->header.flags))
+			lower_key = &((struct leaf *)lower)->items[0].key;
+		else
+			lower_key = lower->keys;
+		memcpy(c->keys, lower_key, sizeof(struct key));
+		memcpy(c->keys + 1, key, sizeof(struct key));
+		c->blockptrs[0] = path->nodes[level-1]->blocknr;
+		c->blockptrs[1] = blocknr;
+		/* the path has an extra ref to root->node */
+		tree_block_release(root, root->node);
+		root->node = t;
+		t->count++;
+		write_tree_block(root, t);
+		path->nodes[level] = t;
+		path->slots[level] = 0;
+		if (c->keys[1].objectid == 0)
+			BUG();
+		return 0;
+	}
+	lower = &path->nodes[level]->node;
+	nritems = lower->header.nritems;
+	if (slot > nritems)
+		BUG();
+	if (nritems == NODEPTRS_PER_BLOCK)
+		BUG();
+	if (slot != nritems) {
+		memmove(lower->keys + slot + 1, lower->keys + slot,
+			(nritems - slot) * sizeof(struct key));
+		memmove(lower->blockptrs + slot + 1, lower->blockptrs + slot,
+			(nritems - slot) * sizeof(u64));
+	}
+	memcpy(lower->keys + slot, key, sizeof(struct key));
+	lower->blockptrs[slot] = blocknr;
+	lower->header.nritems++;
+	if (lower->keys[1].objectid == 0)
+			BUG();
+	write_tree_block(root, path->nodes[level]);
+	return 0;
+}
+
+
+/*
+ * insert a key,blocknr pair into the tree at a given level
+ * If the node at that level in the path doesn't have room,
+ * it is split or shifted as appropriate.
+ */
 int insert_ptr(struct ctree_root *root,
 		struct ctree_path *path, struct key *key,
 		u64 blocknr, int level)
@@ -340,6 +412,15 @@ int insert_ptr(struct ctree_root *root,
 	int mid;
 	int bal_start = -1;
 
+	/*
+	 * check to see if we need to make room in the node for this
+	 * pointer.  If we do, keep walking the tree, making sure there
+	 * is enough room in each level for the required insertions.
+	 *
+	 * The bal array is filled in with any nodes to be inserted
+	 * due to splitting.  Once we've done all the splitting required
+	 * do the inserts based on the data in the bal array.
+	 */
 	memset(bal, 0, ARRAY_SIZE(bal));
 	while(t && t->node.header.nritems == NODEPTRS_PER_BLOCK) {
 		c = &t->node;
@@ -373,6 +454,11 @@ int insert_ptr(struct ctree_root *root,
 		bal_level += 1;
 		t = path->nodes[bal_level];
 	}
+	/*
+	 * bal_start tells us the first level in the tree that needed to
+	 * be split.  Go through the bal array inserting the new nodes
+	 * as needed.  The path is fixed as we go.
+	 */
 	while(bal_start > 0) {
 		b_buffer = bal[bal_start];
 		c = &path->nodes[bal_start]->node;
@@ -390,10 +476,16 @@ int insert_ptr(struct ctree_root *root,
 		if (!bal[bal_start])
 			break;
 	}
+	/* Now that the tree has room, insert the requested pointer */
 	return __insert_ptr(root, path, key, blocknr, path->slots[level] + 1,
 			    level);
 }
 
+/*
+ * how many bytes are required to store the items in a leaf.  start
+ * and nr indicate which items in the leaf to check.  This totals up the
+ * space used both by the item structs and the item data
+ */
 int leaf_space_used(struct leaf *l, int start, int nr)
 {
 	int data_len;
@@ -407,6 +499,10 @@ int leaf_space_used(struct leaf *l, int start, int nr)
 	return data_len;
 }
 
+/*
+ * push some data in the path leaf to the left, trying to free up at
+ * least data_size bytes.  returns zero if the push worked, nonzero otherwise
+ */
 int push_leaf_left(struct ctree_root *root, struct ctree_path *path,
 		   int data_size)
 {
@@ -498,6 +594,10 @@ int push_leaf_left(struct ctree_root *root, struct ctree_path *path,
 	return 0;
 }
 
+/*
+ * split the path's leaf in two, making sure there is at least data_size
+ * available for the resulting leaf level of the path.
+ */
 int split_leaf(struct ctree_root *root, struct ctree_path *path, int data_size)
 {
 	struct tree_buffer *l_buf = path->nodes[0];
@@ -548,9 +648,10 @@ int split_leaf(struct ctree_root *root, struct ctree_path *path, int data_size)
 	       l->data + leaf_data_end(l), data_copy_size);
 	rt_data_off = LEAF_DATA_SIZE -
 		     (l->items[mid].offset + l->items[mid].size);
-	for (i = 0; i < right->header.nritems; i++) {
+
+	for (i = 0; i < right->header.nritems; i++)
 		right->items[i].offset += rt_data_off;
-	}
+
 	l->header.nritems = mid;
 	ret = insert_ptr(root, path, &right->items[0].key,
 			  right_buffer->blocknr, 1);
@@ -570,6 +671,10 @@ int split_leaf(struct ctree_root *root, struct ctree_path *path, int data_size)
 	return ret;
 }
 
+/*
+ * Given a key and some data, insert an item into the tree.
+ * This does all the path init required, making room in the tree if needed.
+ */
 int insert_item(struct ctree_root *root, struct key *key,
 			  void *data, int data_size)
 {
@@ -582,6 +687,7 @@ int insert_item(struct ctree_root *root, struct key *key,
 	unsigned int data_end;
 	struct ctree_path path;
 
+	/* create a root if there isn't one */
 	if (!root->node) {
 		struct tree_buffer *t;
 		t = alloc_free_block(root);
@@ -602,6 +708,8 @@ int insert_item(struct ctree_root *root, struct key *key,
 	slot_orig = path.slots[0];
 	leaf_buf = path.nodes[0];
 	leaf = &leaf_buf->leaf;
+
+	/* make room if needed */
 	if (leaf_free_space(leaf) <  sizeof(struct item) + data_size) {
 		split_leaf(root, &path, data_size);
 		leaf_buf = path.nodes[0];
@@ -638,6 +746,7 @@ int insert_item(struct ctree_root *root, struct key *key,
 		        data_end, old_data - data_end);
 		data_end = old_data;
 	}
+	/* copy the new data in */
 	memcpy(&leaf->items[slot].key, key, sizeof(struct key));
 	leaf->items[slot].offset = data_end - data_size;
 	leaf->items[slot].size = data_size;
@@ -650,6 +759,14 @@ int insert_item(struct ctree_root *root, struct key *key,
 	return 0;
 }
 
+/*
+ * delete the pointer from a given level in the path.  The path is not
+ * fixed up, so after calling this it is not valid at that level.
+ *
+ * If the delete empties a node, the node is removed from the tree,
+ * continuing all the way the root if required.  The root is converted into
+ * a leaf if all the nodes are emptied.
+ */
 int del_ptr(struct ctree_root *root, struct ctree_path *path, int level)
 {
 	int slot;
@@ -705,6 +822,10 @@ int del_ptr(struct ctree_root *root, struct ctree_path *path, int level)
 	return 0;
 }
 
+/*
+ * delete the item at the leaf level in path.  If that empties
+ * the leaf, remove it from the tree
+ */
 int del_item(struct ctree_root *root, struct ctree_path *path)
 {
 	int slot;
@@ -732,6 +853,7 @@ int del_item(struct ctree_root *root, struct ctree_path *path)
 			(leaf->header.nritems - slot - 1));
 	}
 	leaf->header.nritems -= 1;
+	/* delete the leaf if we've emptied it */
 	if (leaf->header.nritems == 0) {
 		if (leaf_buf == root->node) {
 			leaf->header.flags = node_level(0);
@@ -742,6 +864,7 @@ int del_item(struct ctree_root *root, struct ctree_path *path)
 		if (slot == 0)
 			fixup_low_keys(root, path, &leaf->items[0].key, 1);
 		write_tree_block(root, leaf_buf);
+		/* delete the leaf if it is mostly empty */
 		if (leaf_space_used(leaf, 0, leaf->header.nritems) <
 		    LEAF_DATA_SIZE / 4) {
 			/* push_leaf_left fixes the path.
@@ -837,7 +960,7 @@ int main() {
 	int i;
 	int num;
 	int ret;
-	int run_size = 1000000;
+	int run_size = 25000;
 	int max_key = 100000000;
 	int tree_size = 0;
 	struct ctree_path path;