Btrfs: add and improve comments

This improves the comments at the top of many functions.  It didn't
dive into the guts of functions because I was trying to
avoid merging problems with the new allocator and back reference work.

extent-tree.c and volumes.c were both skipped, and there is definitely
more work todo in cleaning and commenting the code.

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

1 files changed, 51 insertions, 3 deletions

diff --git a/fs/btrfs/btrfs_inode.h b/fs/btrfs/btrfs_inode.h
index 0577fda2168a..0b2e623cf421 100644
--- a/fs/btrfs/btrfs_inode.h
+++ b/fs/btrfs/btrfs_inode.h
@@ -25,27 +25,58 @@
 
 /* in memory btrfs inode */
 struct btrfs_inode {
+        /* which subvolume this inode belongs to */
         struct btrfs_root *root;
+
+        /* the block group preferred for allocations.  This pointer is buggy
+         * and needs to be replaced with a bytenr instead
+         */
         struct btrfs_block_group_cache *block_group;
+
+        /* key used to find this inode on disk.  This is used by the code
+         * to read in roots of subvolumes
+         */
         struct btrfs_key location;
+
+        /* the extent_tree has caches of all the extent mappings to disk */
         struct extent_map_tree extent_tree;
+
+        /* the io_tree does range state (DIRTY, LOCKED etc) */
         struct extent_io_tree io_tree;
+
+        /* special utility tree used to record which mirrors have already been
+         * tried when checksums fail for a given block
+         */
         struct extent_io_tree io_failure_tree;
+
+        /* held while inserting checksums to avoid races */
         struct mutex csum_mutex;
+
+        /* held while inesrting or deleting extents from files */
         struct mutex extent_mutex;
+
+        /* held while logging the inode in tree-log.c */
         struct mutex log_mutex;
-        struct inode vfs_inode;
+
+        /* used to order data wrt metadata */
         struct btrfs_ordered_inode_tree ordered_tree;
 
+        /* standard acl pointers */
         struct posix_acl *i_acl;
         struct posix_acl *i_default_acl;
 
         /* for keeping track of orphaned inodes */
         struct list_head i_orphan;
 
+        /* list of all the delalloc inodes in the FS.  There are times we need
+         * to write all the delalloc pages to disk, and this list is used
+         * to walk them all.
+         */
         struct list_head delalloc_inodes;
 
-        /* full 64 bit generation number */
+        /* full 64 bit generation number, struct vfs_inode doesn't have a big
+         * enough field for this.
+         */
         u64 generation;
 
         /*
@@ -57,10 +88,25 @@ struct btrfs_inode {
          */
         u64 logged_trans;
 
-        /* trans that last made a change that should be fully fsync'd */
+        /*
+         * trans that last made a change that should be fully fsync'd.  This
+         * gets reset to zero each time the inode is logged
+         */
         u64 log_dirty_trans;
+
+        /* total number of bytes pending delalloc, used by stat to calc the
+         * real block usage of the file
+         */
         u64 delalloc_bytes;
+
+        /*
+         * the size of the file stored in the metadata on disk.  data=ordered
+         * means the in-memory i_size might be larger than the size on disk
+         * because not all the blocks are written yet.
+         */
         u64 disk_i_size;
+
+        /* flags field from the on disk inode */
         u32 flags;
 
         /*
@@ -68,6 +114,8 @@ struct btrfs_inode {
          * number for new files that are created
          */
         u64 index_cnt;
+
+        struct inode vfs_inode;
 };
 
 static inline struct btrfs_inode *BTRFS_I(struct inode *inode)