new file mode 100644
@@ -0,0 +1,233 @@
+
+ ubifs_repair tests
+ ==================
+
+ There are seven testcases for ubifs_repair on encryption/non-encryption
+ situations:
+ 1) authentication_refuse: Currently authenticated UBIFS image is not
+ supported for repairing, check whether ubifs_repair can refuse
+ authenticated UBIFS image.
+ 2) random_corrupted_repair: Inject random corruption on UBIFS image
+ by writting random data on kinds of mtd devices (eg. nand, nor),
+ check the consistency of UBIFS after repairing.
+ This testcase simulate random bad UBIFS image caused by hardware
+ exceptions(eg. ecc uncorrectable, unwritten), and makes sure that
+ ubifs_repair could make UBIFS be consistent after repairing UBIFS
+ image.
+ 3) cycle_corrupted_repair_fault_inject: Inject memory/io fault while
+ repairing corrupted UBIFS images.
+ This testcase mainly checks whether ubifs_repair has problems (eg.
+ memleak, UAF, null-ptr-def, etc.) in random error paths. Besides,
+ it provides a similar way to simulate powercut during repairing,
+ and checks whether ubifs_repair can fix an UBIFS image after many
+ repairing rounds interrupted by kinds of errors.
+ 4) cycle_powercut_mount_repair: Inject powercut while doing fsstress
+ on mounted UBIFS, check the consistency of UBIFS after repairing.
+ This testscase mainly makes sure that ubifs_repair can make UBIFS
+ image be consistent in common stress cases and powercut cases.
+ 5) powercut_repair_mount: Inject powercut while doing fsstress on
+ mounted UBIFS for kinds of flashes (eg. nand, nor).
+ This testcase mainly makes sure that ubifs_repair can make UBIFS
+ image be consistent on different flashes (eg. nand, nor). Because
+ the min_io_size of nor flash is 1, the UBIFS image on nor flash
+ will be different from nand flash after doing powercut, so we need
+ make sure ubifs_repair can handle these two types of flash.
+ 6) cycle_mount_repair_check: Do fsstress and repair ubifs image, make
+ sure all files(and their data) are not lost after repairing.
+ This testcase mainly checks whether ubifs_repair could corrupt
+ filesystem content in common case.
+ 7) repair_bad_image: For kinds of inconsistent UBIFS images(which
+ can simulate corruptions caused by some potentional UBIFS bug), check
+ repairing result.
+ This testcase mainly checks whether the behavior is in expected after
+ repairing specific inconsistent UBIFS image. There is no debugfs tools
+ (for example: debugfs[ext4], xfs_db) for UBIFS, so no way to inject
+ precise corruption into UBIFS image, we have to prepare inconsistent
+ UBIFS images in advance like e2fsprogs[1] does. (Goto [2] to see how to
+ generate inconsistent UBIFS images). Here's a descriptons of the various
+ test images:
+
+ =========================================================================
+ image | Description | expectancy
+ -------------------------------------------------------------------------
+ good | good image contains | repair success, fs content is
+ | kinds of files. | not changed.
+ -------------------------------------------------------------------------
+ sb_fanout | invalid fanout in | repair failed.
+ | superblock. |
+ -------------------------------------------------------------------------
+ sb_fmt_version | invalid fmt_version | repair failed.
+ | in superblock. |
+ -------------------------------------------------------------------------
+ sb_leb_size | invalid leb_size in | repair failed.
+ | superblock. |
+ -------------------------------------------------------------------------
+ sb_log_lebs | invalid log lebs in | repair failed.
+ | superblock. |
+ -------------------------------------------------------------------------
+ sb_min_io_size | invalid min_io_size | repair failed.
+ | in superblock. |
+ -------------------------------------------------------------------------
+ master_highest_inum | invalid highest_inum| repair success, fs content is
+ | in master nodes. | not changed.
+ -------------------------------------------------------------------------
+ master_lpt | bad lpt pos in | repair success, fs content is
+ | master nodes. | not changed.
+ -------------------------------------------------------------------------
+ master_tnc | bad tnc pos in | repair success, fs content is
+ | master nodes. | not changed.
+ -------------------------------------------------------------------------
+ master_total_dead | bad total_dead in | repair success, fs content is
+ | master nodes. | not changed.
+ -------------------------------------------------------------------------
+ master_total_dirty | bad total_dirty in | repair success, fs content is
+ | master nodes. | not changed.
+ -------------------------------------------------------------------------
+ master_total_free | bad total_free in | repair success, fs content is
+ | master nodes. | not changed.
+ -------------------------------------------------------------------------
+ log | corrupted log area. | repair success, fs content is
+ | | not changed.
+ -------------------------------------------------------------------------
+ lpt_dirty | bad dirty in pnode. | repair success, fs content is
+ | | not changed.
+ -------------------------------------------------------------------------
+ lpt_flags | bad flags in pnode | repair success, fs content is
+ | (eg. index). | not changed.
+ -------------------------------------------------------------------------
+ lpt_free | bad free in pnode. | repair success, fs content is
+ | | not changed.
+ -------------------------------------------------------------------------
+ lpt_pos | bad pos in nnode. | repair success, fs content is
+ | | not changed.
+ -------------------------------------------------------------------------
+ tnc_lv0_key | bad key in lv0 | repair success, fs content is
+ | znode. | not changed.
+ -------------------------------------------------------------------------
+ tnc_lv0_len | bad len in lv0 | repair success, fs content is
+ | znode. | not changed.
+ -------------------------------------------------------------------------
+ tnc_lv0_pos | bad pos in lv0 | repair success, fs content is
+ | znode. | not changed.
+ -------------------------------------------------------------------------
+ tnc_noleaf_key | bad key in non-leaf | repair success, fs content is
+ | znode. | not changed.
+ -------------------------------------------------------------------------
+ tnc_noleaf_len | bad len in non-leaf | repair success, fs content is
+ | znode. | not changed.
+ -------------------------------------------------------------------------
+ tnc_noleaf_pos | bad pos in non-leaf | repair success, fs content is
+ | znode. | not changed.
+ -------------------------------------------------------------------------
+ inode_data | bad data node. | repair success, file content
+ | | is changed, other files are
+ | | not changed.
+ -------------------------------------------------------------------------
+ inode_mode | bad inode mode for | repair success, soft link
+ | solf link file. | file is dropped, other files
+ | | are not changed.
+ -------------------------------------------------------------------------
+ inode_nlink | wrong nlink for | repair success, nlink is
+ | file. | corrected, fs content is not
+ | | changed.
+ -------------------------------------------------------------------------
+ inode_size | wrong inode size | repair success, inode size is
+ | for file. | corrected, fs content is not
+ | | changed.
+ -------------------------------------------------------------------------
+ inode_xcnt | wrong inode | repair success, xattr_cnt is
+ | xattr_cnt for file. | corrected, fs content is not
+ | | changed.
+ -------------------------------------------------------------------------
+ soft_link_data_len | bad inode data_len | repair success, soft link
+ | for solt link file. | file is dropped, other files
+ | | are not changed.
+ -------------------------------------------------------------------------
+ dentry_key | bad dentry key for | repair success, dentry is
+ | file. | removed, other files are
+ | | not changed.
+ -------------------------------------------------------------------------
+ dentry_nlen | inconsistent nlen | repair success, dentry is
+ | and name in dentry | removed, other files are
+ | for file. | not changed.
+ -------------------------------------------------------------------------
+ dentry_type | inconsistent type | repair success, dentry is
+ | between dentry and | removed, other files are
+ | inode for file. | not changed.
+ -------------------------------------------------------------------------
+ xinode_flags | lost UBIFS_XATTR_FL | repair success, xattr is
+ | in xattr inode | removed, other files are
+ | flags for file. | not changed.
+ -------------------------------------------------------------------------
+ xinode_key | bad xattr inode key | repair success, xattr is
+ | for file. | removed, other files are
+ | | not changed.
+ -------------------------------------------------------------------------
+ xinode_mode | bad xattr inode | repair success, xattr is
+ | mode for file. | removed, other files are
+ | | not changed.
+ -------------------------------------------------------------------------
+ xentry_key | bad xattr entry key | repair success, xattr is
+ | for file. | removed, other files are
+ | | not changed.
+ -------------------------------------------------------------------------
+ xentry_nlen | inconsistent nlen | repair success, xattr is
+ | and name in xattr | removed, other files are
+ | entry for file. | not changed.
+ -------------------------------------------------------------------------
+ xentry_type | inconsistent type | repair success, xattr is
+ | between xattr entry | removed, other files are
+ | and xattr inode for | not changed.
+ | file. |
+ -------------------------------------------------------------------------
+ dir_lost | bad dentry for dir. | repair success, dir and files
+ | | under dir are removed, other
+ | | files are not changed.
+ -------------------------------------------------------------------------
+ root_dir | bad '/'. | repair success, create new
+ | | root dir('/').
+ =========================================================================
+
+ Dependence
+ ----------
+ kernel configs:
+ CONFIG_MTD_NAND_NANDSIM=m
+ CONFIG_MTD_MTDRAM=m
+ CONFIG_MTD_UBI=m
+ CONFIG_MTD_UBI_FASTMAP=y
+ CONFIG_UBIFS_FS=m
+ CONFIG_UBIFS_FS_XATTR=y
+ CONFIG_UBIFS_FS_AUTHENTICATION=y
+ CONFIG_FS_ENCRYPTION=y
+ CONFIG_FAILSLAB=y
+ CONFIG_FAIL_PAGE_ALLOC=y
+
+ CONFIG_DEBUG_KMEMLEAK=y // optional
+
+ tools:
+ fsstress [3][4]
+ keyctl [5]
+ fscryptctl [6]
+ setfattr/getfattr [7]
+
+ Running
+ -------
+
+ Please build and install mtd-utils first.
+ Run single case:
+ cd $INSTALL_DIR/libexec/mtd-utils
+ ./powercut_repair_mount.sh
+ ./random_corrupted_repair.sh
+ ./cycle_mount_repair_check.sh
+ Run all cases: sh $INSTALL_DIR/libexec/mtd-utils/ubifs_repair_run_all.sh
+
+ References
+ ----------
+
+ [1] https://git.kernel.org/pub/scm/fs/ext2/e2fsprogs.git/tree/tests/README
+ [2] https://bugzilla.kernel.org/show_bug.cgi?id=218327
+ [3] https://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.git/tree/ltp/fsstress.c
+ [4] https://github.com/linux-test-project/ltp/blob/master/testcases/kernel/fs/fsstress/fsstress.c
+ [5] https://github.com/torvalds/linux/blob/master/security/keys/keyctl.c
+ [6] https://github.com/google/fscryptctl
+ [7] https://github.com/philips/attr/tree/master