UBIFS: add some comments

Signed-off-by: Adrian Hunter <ext-adrian.hunter@nokia.com>

27 files changed, 159 insertions, 65 deletions

diff --git a/fs/ubifs/budget.c b/fs/ubifs/budget.c
index c0f67dbef610..cc8ddd9179a2 100644
--- a/fs/ubifs/budget.c
+++ b/fs/ubifs/budget.c
@@ -21,7 +21,7 @@
  */
 
 /*
- * This file implements budgeting unit which is responsible for UBIFS space
+ * This file implements the budgeting unit which is responsible for UBIFS space
  * management.
  *
  * Factors such as compression, wasted space at the ends of LEBs, space in other
diff --git a/fs/ubifs/commit.c b/fs/ubifs/commit.c
index a6bfba8155f6..e3ab3cf6e87f 100644
--- a/fs/ubifs/commit.c
+++ b/fs/ubifs/commit.c
@@ -20,6 +20,29 @@
  *         Artem Bityutskiy
  */
 
+/*
+ * This file implements functions that manage the running of the commit process.
+ * Each affected module has its own functions to accomplish their part in the
+ * commit and those functions are called here.
+ *
+ * The commit is the process whereby all updates to the index and LEB properties
+ * are written out together and the journal becomes empty. This keeps the
+ * file system consistent - at all times the state can be recreated by reading
+ * the index and LEB properties and then replaying the journal.
+ *
+ * The commit is split into two parts named "commit start" and "commit end".
+ * During commit start, the commit process has exclusive access to the journal
+ * by holding the commit semaphore down for writing. As few I/O operations as
+ * possible are performed during commit start, instead the nodes that are to be
+ * written are merely identified. During commit end, the commit semaphore is no
+ * longer held and the journal is again in operation, allowing users to continue
+ * to use the file system while the bulk of the commit I/O is performed. The
+ * purpose of this two-step approach is to prevent the commit from causing any
+ * latency blips. Note that in any case, the commit does not prevent lookups
+ * (as permitted by the TNC mutex), or access to VFS data structures e.g. page
+ * cache.
+ */
+
 #include <linux/freezer.h>
 #include <linux/kthread.h>
 #include "ubifs.h"
diff --git a/fs/ubifs/compat.c b/fs/ubifs/compat.c
index 10e60f1c40c8..c444c7920fa3 100644
--- a/fs/ubifs/compat.c
+++ b/fs/ubifs/compat.c
@@ -1,7 +1,7 @@
 /*
  * This file is part of UBIFS.
  *
- * Copyright (C) 2006, 2007 Nokia Corporation
+ * Copyright (C) 2006-2008 Nokia Corporation
  *
  * This program is free software; you can redistribute it and/or modify it
  * under the terms of the GNU General Public License version 2 as published by
diff --git a/fs/ubifs/compress.c b/fs/ubifs/compress.c
index 9db1cdee1062..9d4dbe2f1d3b 100644
--- a/fs/ubifs/compress.c
+++ b/fs/ubifs/compress.c
@@ -22,6 +22,11 @@
  *          Zoltan Sogor
  */
 
+/*
+ * This file provides a single place to access to compression and
+ * decompression.
+ */
+
 #include <linux/crypto.h>
 #include "ubifs.h"
 
diff --git a/fs/ubifs/debug.c b/fs/ubifs/debug.c
index a3289be1add2..514cd79e8989 100644
--- a/fs/ubifs/debug.c
+++ b/fs/ubifs/debug.c
@@ -1,7 +1,7 @@
 /*
  * This file is part of UBIFS.
  *
- * Copyright (C) 2006, 2007 Nokia Corporation
+ * Copyright (C) 2006-2008 Nokia Corporation
  *
  * This program is free software; you can redistribute it and/or modify it
  * under the terms of the GNU General Public License version 2 as published by
@@ -24,7 +24,7 @@
  * This file implements most of the debugging stuff which is compiled in only
  * when it is enabled. But some debugging check functions are implemented in
  * corresponding subsystem, just because they are closely related and utilize
- * various local functions of the subsystems.
+ * various local functions of those subsystems.
  */
 
 #define UBIFS_DBG_PRESERVE_KMALLOC
diff --git a/fs/ubifs/dir.c b/fs/ubifs/dir.c
index 89084e698573..1d2b2909b99b 100644
--- a/fs/ubifs/dir.c
+++ b/fs/ubifs/dir.c
@@ -27,7 +27,7 @@
  *
  * All FS operations in this file allocate budget before writing anything to the
  * media. If they fail to allocate it, the error is returned. The only
- * exception are 'ubifs_unlink()' and 'ubifs_rmdir()' which keep working even
+ * exceptions are 'ubifs_unlink()' and 'ubifs_rmdir()' which keep working even
  * if they unable to allocate the budget, because deletion %-ENOSPC failure is
  * not what users are usually ready to get. UBIFS budgeting subsystem has some
  * space reserved for these purposes.
diff --git a/fs/ubifs/file.c b/fs/ubifs/file.c
index 54803516e1c2..fb97d4d4049e 100644
--- a/fs/ubifs/file.c
+++ b/fs/ubifs/file.c
@@ -28,8 +28,8 @@
  * page is dirty and is used for budgeting purposes - dirty pages should not be
  * budgeted. The PG_checked flag is set if full budgeting is required for the
  * page e.g., when it corresponds to a file hole or it is just beyond the file
- * size. The budgeting is done in 'ubifs_prepare_write()', because it is OK to
- * fail in this function, and the budget is released in 'ubifs_writepage()'. So
+ * size. The budgeting is done in 'ubifs_write_begin()', because it is OK to
+ * fail in this function, and the budget is released in 'ubifs_write_end()'. So
  * the PG_private and PG_checked flags carry the information about how the page
  * was budgeted, to make it possible to release the budget properly.
  *
diff --git a/fs/ubifs/find.c b/fs/ubifs/find.c
index 28c6392b47c7..c52c0a81c59f 100644
--- a/fs/ubifs/find.c
+++ b/fs/ubifs/find.c
@@ -21,8 +21,9 @@
  */
 
 /*
- * This file contains "find" functions, like "find a dirty LEB", "find an empty
- * LEB", etc.
+ * This file contains functions for finding LEBs for various purposes e.g.
+ * garbage collection. In general, lprops category heaps and lists are used
+ * for fast access, falling back on scanning the LPT as a last resort.
  */
 
 #include <linux/sort.h>
diff --git a/fs/ubifs/gc.c b/fs/ubifs/gc.c
index 3d1204c711de..66583d1aea17 100644
--- a/fs/ubifs/gc.c
+++ b/fs/ubifs/gc.c
@@ -20,6 +20,19 @@
  *          Artem Bityutskiy
  */
 
+/*
+ * This file implements garbage collection. The procedure for garbage collection
+ * is different depending on whether a LEB as an index LEB (contains index
+ * nodes) or not. For non-index LEBs, garbage collection finds a LEB which
+ * contains a lot of dirty space (obsolete nodes), and copies the non-obsolete
+ * nodes to the journal, at which point the garbage-collected LEB is free to be
+ * reused. For index LEBs, garbage collection marks the non-obsolete index nodes
+ * dirty in the TNC, and after the next commit, the garbage-collected LEB is
+ * to be reused. Garbage collection will cause the number of dirty index nodes
+ * to grow, however sufficient space is reserved for the index to ensure the
+ * commit will never run out of space.
+ */
+
 #include <linux/pagemap.h>
 #include "ubifs.h"
 
diff --git a/fs/ubifs/io.c b/fs/ubifs/io.c
index cc97f67a8229..30071b42bba3 100644
--- a/fs/ubifs/io.c
+++ b/fs/ubifs/io.c
@@ -26,21 +26,21 @@
  * This file implements UBIFS I/O subsystem which provides various I/O-related
  * helper functions (reading/writing/checking/validating nodes) and implements
  * write-buffering support. Write buffers help to save space which otherwise
- * would have been wasted for padding to the nearest minimal I/O unit
- * boundary. Instead, data first goes to the write-buffer and flushed when the
- * buffer is full or when it is not used for some time (by timer). Similar
- * mechanism is used by JFFS2.
+ * would have been wasted for padding to the nearest minimal I/O unit boundary.
+ * Instead, data first goes to the write-buffer and is flushed when the
+ * buffer is full or when it is not used for some time (by timer). This is
+ * similarto the mechanism is used by JFFS2.
  *
  * Write-buffers are defined by 'struct ubifs_wbuf' objects and protected by
- * rw-semaphores defined inside these objects. Since sometimes upper-level code
- * has to lock write-buffer (e.g. journal space reservation code), many
+ * mutexes defined inside these objects. Since sometimes upper-level code
+ * has to lock the write-buffer (e.g. journal space reservation code), many
  * functions related to write-buffers have "nolock" suffix which means that the
  * caller has to lock the write-buffer before calling this function.
  *
- * UBIFS stores nodes at 64 bit-aligned addresses. If node length is not
+ * UBIFS stores nodes at 64 bit-aligned addresses. If the node length is not
  * aligned, UBIFS starts the next node from the aligned address, and the padded
  * bytes may contain any rubbish. In other words, UBIFS does not put padding
- * bytes to those small gaps. Common headers of nodes store real node lengths,
+ * bytes in those small gaps. Common headers of nodes store real node lengths,
  * not aligned lengths. Indexing nodes also store real lengths in branches.
  *
  * UBIFS uses padding when it pads to the next min. I/O unit. In this case it
diff --git a/fs/ubifs/ioctl.c b/fs/ubifs/ioctl.c
index fbd98b70039e..ba6f7decd4a3 100644
--- a/fs/ubifs/ioctl.c
+++ b/fs/ubifs/ioctl.c
@@ -22,6 +22,8 @@
  *          Adrian Hunter
  */
 
+/* This file implements EXT2-compatible extended attribute ioctl() calls */
+
 #include <linux/compat.h>
 #include <linux/smp_lock.h>
 #include "ubifs.h"
diff --git a/fs/ubifs/journal.c b/fs/ubifs/journal.c
index d63ce5d433a1..ea316be4dc14 100644
--- a/fs/ubifs/journal.c
+++ b/fs/ubifs/journal.c
@@ -24,10 +24,10 @@
  * This file implements UBIFS journal.
  *
  * The journal consists of 2 parts - the log and bud LEBs. The log has fixed
- * length and position, while the bud logical eraseblock is any LEB in the main
+ * length and position, while a bud logical eraseblock is any LEB in the main
  * area. Buds contain file system data - data nodes, inode nodes, etc. The log
  * contains only references to buds and some other stuff like commit
- * start/commit end nodes. The idea is that when we commit the journal, we do
+ * start node. The idea is that when we commit the journal, we do
  * not copy the data, the buds just become indexed. Since after the commit the
  * nodes in bud eraseblocks become leaf nodes of the file system index tree, we
  * use term "bud". Analogy is obvious, bud eraseblocks contain nodes which will
@@ -36,24 +36,25 @@
  * The journal is multi-headed because we want to write data to the journal as
  * optimally as possible. It is nice to have nodes belonging to the same inode
  * in one LEB, so we may write data owned by different inodes to different
- * journal heads.
+ * journal heads, although at present only one data head is used.
  *
  * For recovery reasons, the base head contains all inode nodes, all directory
  * entry nodes and all truncate nodes.  This means that the other heads contain
  * only data nodes.
  *
- * Obviously, bud LEBs may be half-indexed. For example, if there is a LEB in
- * the main area with a lot of dirt, and UBIFS cleans it up using in-place
- * garbage collection, then the journal may use this half-free LEB as a bud
- * LEB.
+ * Bud LEBs may be half-indexed. For example, if the bud was not full at the
+ * time of commit, the bud is retained to continue to be used in the journal,
+ * even though the "front" of the LEB is now indexed. In that case, the log
+ * reference contains the offset where the bud starts for the purposes of the
+ * journal.
  *
  * The journal size has to be limited, because the larger is the journal, the
  * longer it takes to mount UBIFS (scanning the journal) and the more memory it
  * takes (indexing in the TNC).
  *
- * Note, all the journal write operations like 'ubifs_jrn_update()' here which
- * write multiple UBIFS nodes to the journal at one go are atomic with respect
- * to unclean reboots. Should the unclean reboot happen, the replay code drops
+ * Note, all the journal write operations like 'ubifs_jrn_update()' here, which
+ * write multiple UBIFS nodes to the journal at one go, are atomic with respect
+ * to unclean reboots. Should the unclean reboot happen, the recovery code drops
  * all the nodes.
  */
 
diff --git a/fs/ubifs/log.c b/fs/ubifs/log.c
index 6a0f5fe8f28e..dcd3a8d54e90 100644
--- a/fs/ubifs/log.c
+++ b/fs/ubifs/log.c
@@ -23,7 +23,7 @@
 /*
  * This file is a part of UBIFS journal implementation and contains various
  * functions which manipulate the log. The log is a fixed area on the flash
- * which does not contain any data but refers buds. The log is a part of the
+ * which does not contain any data but refers to buds. The log is a part of the
  * journal.
  */
 
diff --git a/fs/ubifs/lprops.c b/fs/ubifs/lprops.c
index 527b8632e805..b8b95bd11872 100644
--- a/fs/ubifs/lprops.c
+++ b/fs/ubifs/lprops.c
@@ -20,6 +20,14 @@
  *          Artem Bityutskiy
  */
 
+/*
+ * This file implements the functions that access LEB properties and their
+ * categories. LEBs are categorized based on the needs of UBIFS, and the
+ * categories are stored as either heaps or lists to provide a fast way of
+ * finding a LEB in a particular category. For example, UBIFS may need to find
+ * an empty LEB for the journal, or a very dirty LEB for garbage collection.
+ */
+
 #include "ubifs.h"
 
 #if defined(CONFIG_UBIFS_FS_DEBUG_CHK_LPROPS) || \
diff --git a/fs/ubifs/lpt.c b/fs/ubifs/lpt.c
index bf9908da269f..e0329f81c352 100644
--- a/fs/ubifs/lpt.c
+++ b/fs/ubifs/lpt.c
@@ -20,6 +20,29 @@
  *          Artem Bityutskiy
  */
 
+/*
+ * This file implements the LEB properties tree (LPT) area. The LPT area
+ * contains the LEB properties tree, a table of LPT area eraseblocks (ltab), and
+ * (for the "big" model) a table of saved LEB numbers (lsave). The LPT area sits
+ * between the log and the orphan area.
+ *
+ * The LPT area is like a miniature self-contained file system. It is required
+ * that it never runs out of space, is fast to access and update, and scales
+ * logarithmically. The LEB properties tree is implemented as a wandering tree
+ * much like the TNC, and the LPT area has its own garbage collection.
+ *
+ * The LPT has two slightly different forms called the "small model" and the
+ * "big model". The small model is used when the entire LEB properties table
+ * can be written into a single eraseblock. In that case, garbage collection
+ * consists of just writing the whole table, which therefore makes all other
+ * eraseblocks reusable. In the case of the big model, dirty eraseblocks are
+ * selected for garbage collection, which consists are marking the nodes in
+ * that LEB as dirty, and then only the dirty nodes are written out. Also, in
+ * the case of the big model, a table of LEB numbers is saved so that the entire
+ * LPT does not to be scanned looking for empty eraseblocks when UBIFS is first
+ * mounted.
+ */
+
 #include <linux/crc16.h>
 #include "ubifs.h"
 
diff --git a/fs/ubifs/master.c b/fs/ubifs/master.c
index 12dc1a08f0fb..593b8c46a8ea 100644
--- a/fs/ubifs/master.c
+++ b/fs/ubifs/master.c
@@ -20,6 +20,8 @@
  *          Adrian Hunter
  */
 
+/* This file implements reading and writing the master node */
+
 #include "ubifs.h"
 
 /**
diff --git a/fs/ubifs/misc.h b/fs/ubifs/misc.h
index 4f3702d7b3c5..41dc8b4d9f42 100644
--- a/fs/ubifs/misc.h
+++ b/fs/ubifs/misc.h
@@ -1,7 +1,7 @@
 /*
  * This file is part of UBIFS.
  *
- * Copyright (C) 2006, 2007 Nokia Corporation
+ * Copyright (C) 2006-2008 Nokia Corporation
  *
  * This program is free software; you can redistribute it and/or modify it
  * under the terms of the GNU General Public License version 2 as published by
diff --git a/fs/ubifs/recovery.c b/fs/ubifs/recovery.c
index fbdb7e30b655..b9c20de7e31d 100644
--- a/fs/ubifs/recovery.c
+++ b/fs/ubifs/recovery.c
@@ -1,7 +1,7 @@
 /*
  * This file is part of UBIFS.
  *
- * Copyright (C) 2006, 2007 Nokia Corporation
+ * Copyright (C) 2006-2008 Nokia Corporation
  *
  * This program is free software; you can redistribute it and/or modify it
  * under the terms of the GNU General Public License version 2 as published by
@@ -20,6 +20,16 @@
  *          Artem Bityutskiy
  */
 
+/*
+ * This file implements functions needed to recover from unclean un-mounts.
+ * When UBIFS is mounted, it checks a flag on the master node to determine if
+ * an un-mount was completed sucessfully. If not, the process of mounting
+ * incorparates additional checking and fixing of on-flash data structures.
+ * UBIFS always cleans away all remnants of an unclean un-mount, so that
+ * errors do not accumulate. However UBIFS defers recovery if it is mounted
+ * read-only, and the flash is not modified in that case.
+ */
+
 #include <linux/crc32.h>
 #include "ubifs.h"
 
diff --git a/fs/ubifs/replay.c b/fs/ubifs/replay.c
index 9d18f4a0da68..7088ffe3bfd4 100644
--- a/fs/ubifs/replay.c
+++ b/fs/ubifs/replay.c
@@ -26,8 +26,8 @@
  *
  * The larger is the journal, the longer it takes to scan it, so the longer it
  * takes to mount UBIFS. This is why the journal has limited size which may be
- * changed depending in the system requirements. But larger journal assumes
- * faster I/O speed because it allows to change the index seldom. So this is a
+ * changed depending on the system requirements. But a larger journal gives
+ * faster I/O speed because it writes the index less frequently. So this is a
  * trade-off. Also, the journal is indexed by the in-memory index (TNC), so the
  * larger is the journal, the more memory its index may consume.
  */
diff --git a/fs/ubifs/scan.c b/fs/ubifs/scan.c
index 5f3a4447d020..6b09297c6526 100644
--- a/fs/ubifs/scan.c
+++ b/fs/ubifs/scan.c
@@ -1,7 +1,7 @@
 /*
  * This file is part of UBIFS.
  *
- * Copyright (C) 2006, 2007 Nokia Corporation
+ * Copyright (C) 2006-2008 Nokia Corporation
  *
  * This program is free software; you can redistribute it and/or modify it
  * under the terms of the GNU General Public License version 2 as published by
@@ -20,6 +20,13 @@
  *          Artem Bityutskiy
  */
 
+/*
+ * This file implements the scan which is a general-purpose function for
+ * determining what nodes are in an eraseblock. The scan is used to replay the
+ * journal, to do garbage collection. for the TNC in-the-gaps method, and by
+ * debugging functions.
+ */
+
 #include "ubifs.h"
 
 /**
diff --git a/fs/ubifs/shrinker.c b/fs/ubifs/shrinker.c
index a43fbd0b12e0..cb3266db61e7 100644
--- a/fs/ubifs/shrinker.c
+++ b/fs/ubifs/shrinker.c
@@ -28,12 +28,12 @@
  * would add additional overhead to the file system fast paths. So the shrinker
  * just walks the TNC tree when searching for znodes to free.
  *
- * If the root of a TNC sub-tree is clean and old enough, the children are as
- * well clean and old enough. So the shrinker walks the TNC in level order and
+ * If the root of a TNC sub-tree is clean and old enough, then the children are
+ * also clean and old enough. So the shrinker walks the TNC in level order and
  * dumps entire sub-trees.
  *
  * The age of znodes is just the time-stamp when they were last looked at.
- * Current shrinker first tries to evict old znodes, then young ones.
+ * The current shrinker first tries to evict old znodes, then young ones.
  *
  * Since the shrinker is global, it has to protect against races with FS
  * un-mounts, which is done by the 'ubifs_infos_lock' and 'c->umount_mutex'.
diff --git a/fs/ubifs/super.c b/fs/ubifs/super.c
index 9f8b4220e38a..e38c8ce5795b 100644
--- a/fs/ubifs/super.c
+++ b/fs/ubifs/super.c
@@ -20,9 +20,7 @@
  *          Adrian Hunter
  */
 
-/*
- * This file implements VFS superblock operations.
- */
+/* This file implements VFS superblock operations */
 
 #include <linux/kthread.h>
 #include <linux/seq_file.h>
diff --git a/fs/ubifs/tnc.c b/fs/ubifs/tnc.c
index 4d749398882b..378b41a60086 100644
--- a/fs/ubifs/tnc.c
+++ b/fs/ubifs/tnc.c
@@ -25,10 +25,9 @@
  * the UBIFS B-tree.
  *
  * At the moment the locking rules of the TNC tree are quite simple and
- * straightforward. We just have on mutex and lock it when we traverse the
+ * straightforward. We just have a mutex and lock it when we traverse the
  * tree. If a znode is not in memory, we read it from flash while still having
- * the mutex locked. This would be performance killer for "big" systems, but it
- * should be fine for embedded ones. And after all, this can be improved later.
+ * the mutex locked.
  */
 
 #include <linux/crc32.h>
diff --git a/fs/ubifs/tnc_commit.c b/fs/ubifs/tnc_commit.c
index b4bd6daec846..bf2ce0711228 100644
--- a/fs/ubifs/tnc_commit.c
+++ b/fs/ubifs/tnc_commit.c
@@ -20,6 +20,8 @@
  *          Artem Bityutskiy
  */
 
+/* This file implements TNC functions for committing */
+
 #include "ubifs.h"
 
 /**
diff --git a/fs/ubifs/ubifs-media.h b/fs/ubifs/ubifs-media.h
index 0d9da858a832..6fbbf311a6ca 100644
--- a/fs/ubifs/ubifs-media.h
+++ b/fs/ubifs/ubifs-media.h
@@ -21,19 +21,19 @@
  */
 
 /*
- * This file describes UBIFS on-flash format and contains definition of all the
+ * This file describes UBIFS on-flash format and contains definitions of all the
  * relevant data structures and constants.
  *
- * All UBIFS on-flash objects are stored in form of nodes. All nodes start with
- * magic UBIFS node number and have the same common header. Nodes always sit at
- * 8-byte aligned positions on the media and node header sizes are also 8-byte
- * aligned (except of the padding node).
+ * All UBIFS on-flash objects are stored in the form of nodes. All nodes start
+ * with the UBIFS node magic number and have the same common header. Nodes
+ * always sit at 8-byte aligned positions on the media and node header sizes are
+ * also 8-byte aligned (except of the padding node).
  */
 
 #ifndef __UBIFS_MEDIA_H__
 #define __UBIFS_MEDIA_H__
 
-/* UBIFS nodes magic number (must not have the padding byte first or last) */
+/* UBIFS node magic number (must not have the padding byte first or last) */
 #define UBIFS_NODE_MAGIC  0x06101831
 
 /* UBIFS on-flash format version */
diff --git a/fs/ubifs/ubifs.h b/fs/ubifs/ubifs.h
index a54036f24b13..5c7209f1447a 100644
--- a/fs/ubifs/ubifs.h
+++ b/fs/ubifs/ubifs.h
@@ -1,7 +1,7 @@
 /*
  * This file is part of UBIFS.
  *
- * Copyright (C) 2006, 2007 Nokia Corporation
+ * Copyright (C) 2006-2008 Nokia Corporation
  *
  * This program is free software; you can redistribute it and/or modify it
  * under the terms of the GNU General Public License version 2 as published by
diff --git a/fs/ubifs/xattr.c b/fs/ubifs/xattr.c
index c8edc970c58e..8043c33f52b1 100644
--- a/fs/ubifs/xattr.c
+++ b/fs/ubifs/xattr.c
@@ -29,7 +29,7 @@
  * which are almost identical to directory entries, but have different key type.
  *
  * In other words, the situation with extended attributes is very similar to
- * directories. Indeed, any inode (but of course not xattr inode) may have a
+ * directories. Indeed, any inode (but of course not xattr inodes) may have a
  * number of associated xentries, just like directory inodes have associated
  * directory entries. Extended attribute entries store the name of the extended
  * attribute, the host inode number, and the extended attribute inode number.
@@ -45,8 +45,8 @@
  *
  * Extended attributes are synchronous, which means they are written to the
  * flash media synchronously and there is no write-back for extended attribute
- * inodes. The extended attribute values are stored in compressed form on the
- * media.
+ * inodes. The extended attribute values are not stored in compressed form on
+ * the media.
  *
  * Since extended attributes are represented by regular inodes, they are cached
  * in the VFS inode cache. The xentries are cached in the LNC cache (see
@@ -59,7 +59,7 @@
 #include <linux/posix_acl_xattr.h>
 #include "ubifs.h"
 
-/* How much bytes an extended attribute adds to the host inode */
+/* How many bytes an extended attribute adds to the host inode */
 #define CALC_XATTR_BYTES(data_len) ALIGN(UBIFS_INO_NODE_SZ + (data_len) + 1, 8)
 
 /*
@@ -89,7 +89,7 @@ static struct file_operations none_file_operations;
  *
  * This is a helper function which creates an extended attribute of name @nm
  * and value @value for inode @host. The host inode is also updated on flash
- * because this ctime and extended attribute accounting data changes. This
+ * because the ctime and extended attribute accounting data changes. This
  * function returns zero in case of success and a negative error code in case
  * of failure.
  */
@@ -105,8 +105,8 @@ static int create_xattr(struct ubifs_info *c, struct inode *host,
 	/*
 	 * Linux limits the maximum size of the extended attribute names list
 	 * to %XATTR_LIST_MAX. This means we should not allow creating more*
-	 * extended attributes if name list becomes larger. This limitation is
-	 * artificial for UBIFS, though.
+	 * extended attributes if the name list becomes larger. This limitation
+	 * is artificial for UBIFS, though.
 	 */
 	if (host_ui->xattr_names + host_ui->xattr_cnt +
 					nm->len + 1 > XATTR_LIST_MAX)
@@ -149,15 +149,15 @@ static int create_xattr(struct ubifs_info *c, struct inode *host,
 	host_ui->xattr_names += nm->len;
 
 	/*
-	 * We do not use i_size_write() because nobody can race with us as are
-	 * holding host @host->i_mutex - every xattr operation for this inode
-	 * is serialized by it.
+	 * We do not use i_size_write() because nobody can race with us as we
+	 * are holding host @host->i_mutex - every xattr operation for this
+	 * inode is serialized by it.
 	 */
 	inode->i_size = size;
 	ui->data_len = size;
 
 	/*
-	 * Note, this is important that 'ubifs_jrn_update()' writes the @host
+	 * Note, it is important that 'ubifs_jrn_update()' writes the @host
 	 * inode last, so when it gets synchronized and the write-buffer is
 	 * flushed, the extended attribute is flushed as well.
 	 */
@@ -232,9 +232,9 @@ static int change_xattr(struct ubifs_info *c, struct inode *host,
 
 	/*
 	 * It is important to write the host inode after the xattr inode
-	 * because if the host inode gets synchronized, the extended attribute
-	 * inode gets synchronized to as it goes before the host inode in the
-	 * write-buffer.
+	 * because if the host inode gets synchronized, then the extended
+	 * attribute inode gets synchronized, because it goes before the host
+	 * inode in the write-buffer.
 	 */
 	err = ubifs_jrn_write_2_inodes(c, inode, host, IS_DIRSYNC(host));
 	if (err)
@@ -446,8 +446,8 @@ ssize_t ubifs_listxattr(struct dentry *dentry, char *buffer, size_t size)
 	len = host_ui->xattr_names + host_ui->xattr_cnt;
 	if (!buffer)
 		/*
-		 * We should return minimum buffer size which will fit
-		 * zero-terminated list of all the extended attribute names.
+		 * We should return the minimum buffer size which will fit a
+		 * null-terminated list of all the extended attribute names.
 		 */
 		return len;