ext4: update code documentation

 * that need to be committed during a fast commit in another in memory queue of

 * inodes. During the commit operation, we commit in the following order:

 *

 * [1] Lock inodes for any further data updates by setting COMMITTING state

 * [2] Submit data buffers of all the inodes

 * [3] Wait for [2] to complete

 * [4] Commit all the directory entry updates in the fast commit space

 * [5] Commit all the changed inode structures

 * [6] Write tail tag (this tag ensures the atomicity, please read the following

 * [1] Prepare all the inodes to write out their data by setting

 *     "EXT4_STATE_FC_FLUSHING_DATA". This ensures that inode cannot be

 *     deleted while it is being flushed.

 * [2] Flush data buffers to disk and clear "EXT4_STATE_FC_FLUSHING_DATA"

 *     state.

 * [3] Lock the journal by calling jbd2_journal_lock_updates. This ensures that

 *     all the exsiting handles finish and no new handles can start.

 * [4] Mark all the fast commit eligible inodes as undergoing fast commit

 *     by setting "EXT4_STATE_FC_COMMITTING" state.

 * [5] Unlock the journal by calling jbd2_journal_unlock_updates. This allows

 *     starting of new handles. If new handles try to start an update on

 *     any of the inodes that are being committed, ext4_fc_track_inode()

 *     will block until those inodes have finished the fast commit.

 * [6] Commit all the directory entry updates in the fast commit space.

 * [7] Commit all the changed inodes in the fast commit space and clear

 *     "EXT4_STATE_FC_COMMITTING" for these inodes.

 * [8] Write tail tag (this tag ensures the atomicity, please read the following

 *     section for more details).

 * [7] Wait for [4], [5] and [6] to complete.

 *

 * All the inode updates must call ext4_fc_start_update() before starting an

 * update. If such an ongoing update is present, fast commit waits for it to

 * complete. The completion of such an update is marked by

 * ext4_fc_stop_update().

 * All the inode updates must be enclosed within jbd2_jounrnal_start()

 * and jbd2_journal_stop() similar to JBD2 journaling.

 *

 * Fast Commit Ineligibility

 * -------------------------

 * similarly. Thus, by converting a non-idempotent procedure into a series of

 * idempotent outcomes, fast commits ensured idempotence during the replay.

 *

 * Locking

 * -------

 * sbi->s_fc_lock protects the fast commit inodes queue and the fast commit

 * dentry queue. ei->i_fc_lock protects the fast commit related info in a given

 * inode. Most of the code avoids acquiring both the locks, but if one must do

 * that then sbi->s_fc_lock must be acquired before ei->i_fc_lock.

 *

 * TODOs

 * -----

 *

 *    fast commit recovery even if that area is invalidated by later full

 *    commits.

 *

 * 1) Fast commit's commit path locks the entire file system during fast

 *    commit. This has significant performance penalty. Instead of that, we

 *    should use ext4_fc_start/stop_update functions to start inode level

 *    updates from ext4_journal_start/stop. Once we do that we can drop file

 *    system locking during commit path.

 * 1) Handle more ineligible cases.

 *

 * 2) Handle more ineligible cases.

 * 2) Change ext4_fc_commit() to lookup logical to physical mapping using extent

 *    status tree. This would get rid of the need to call ext4_fc_track_inode()

 *    before acquiring i_data_sem. To do that we would need to ensure that

 *    modified extents from the extent status tree are not evicted from memory.

 */

#include <trace/events/ext4.h>