[RFC PATCH mtd-utils 110/110] tests: ubifs_tools: Add README
Zhihao Cheng
chengzhihao1 at huawei.com
Thu Jun 6 21:26:15 PDT 2024
Add document for fsck.ubifs and mkfs.ubifs testcases, explain all
testcases and how to run them.
Signed-off-by: Zhihao Cheng <chengzhihao1 at huawei.com>
---
tests/ubifs_tools-tests/README.txt | 303 +++++++++++++++++++++++++++++++++++++
1 file changed, 303 insertions(+)
create mode 100644 tests/ubifs_tools-tests/README.txt
diff --git a/tests/ubifs_tools-tests/README.txt b/tests/ubifs_tools-tests/README.txt
new file mode 100644
index 00000000..3848e23f
--- /dev/null
+++ b/tests/ubifs_tools-tests/README.txt
@@ -0,0 +1,303 @@
+
+ ubifs_tools tests
+ ==================
+
+ There are seven testcases for fsck.ubifs on encryption/non-encryption
+ situations:
+ 1) authentication_refuse: Currently authenticated UBIFS image is not
+ supported for fsck.ubifs, check whether fsck.ubifs can refuse the
+ authenticated UBIFS image.
+ 2) random_corrupted_fsck: Inject random corruption on UBIFS image
+ by writting random data on kinds of mtd devices (eg. nand, nor),
+ check the consistency of UBIFS after fsck.
+ This testcase simulate random bad UBIFS image caused by hardware
+ exceptions(eg. ecc uncorrectable, unwritten), and makes sure that
+ fsck.ubifs could make UBIFS be consistent after repairing UBIFS
+ image.
+ 3) cycle_corrupted_fsck_fault_inject: Inject memory/io fault while
+ doing fsck for corrupted UBIFS images.
+ This testcase mainly checks whether fsck.ubifs has problems (eg.
+ UAF, null-ptr-def, etc.) in random error paths. Besides, it
+ provides a similar way to simulate powercut during fsck, and
+ checks whether the fsck.ubifs can fix an UBIFS image after many
+ rounds interrupted by kinds of errors.
+ 4) cycle_powercut_mount_fsck: Inject powercut while doing fsstress
+ on mounted UBIFS, check the consistency of UBIFS after fsck.
+ This testscase mainly makes sure that fsck.ubifs can make UBIFS
+ image be consistent in common stress cases and powercut cases.
+ 5) powercut_fsck_mount: Inject powercut while doing fsstress on
+ mounted UBIFS for kinds of flashes (eg. nand, nor).
+ This testcase mainly makes sure that fsck.ubifs 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 fsck.ubifs can handle these two types of flash.
+ 6) cycle_mount_fsck_check: Do fsstress and fsck ubifs image, make
+ sure all files(and their data) are not lost after fsck.
+ This testcase mainly checks whether fsck.ubifs could corrupt the
+ filesystem content in common case.
+ 7) fsck_bad_image: For kinds of inconsistent UBIFS images(which
+ can simulate corruptions caused by some potentional UBIFS bug), check
+ the result of fsck.
+ 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).
+ Original UBIFS image content:
+ /
+ ├── corrupt_file (xattr - user.corrupt:123, 2K data)
+ ├── dir
+ │ ├── block_dev
+ │ ├── char_dev
+ │ ├── dir
+ │ └── file (content: '123')
+ ├── hardl_corrupt_file => corrupt_file
+ └── softl_corrupt_file -> corrupt_file
+ Here's a descriptons of the various test images:
+ =========================================================================
+ image | Description | expectancy
+ -------------------------------------------------------------------------
+ good | good image contains | fsck success, fs content is
+ | kinds of files. | not changed.
+ -------------------------------------------------------------------------
+ sb_fanout | invalid fanout in | fsck failed.
+ | superblock. |
+ -------------------------------------------------------------------------
+ sb_fmt_version | invalid fmt_version | fsck failed.
+ | in superblock. |
+ -------------------------------------------------------------------------
+ sb_leb_size | invalid leb_size in | fsck failed.
+ | superblock. |
+ -------------------------------------------------------------------------
+ sb_log_lebs | invalid log lebs in | fsck failed.
+ | superblock. |
+ -------------------------------------------------------------------------
+ sb_min_io_size | invalid min_io_size | fsck failed.
+ | in superblock. |
+ -------------------------------------------------------------------------
+ master_highest_inum | invalid highest_inum| fsck success, fs content is
+ | in master nodes. | not changed.
+ -------------------------------------------------------------------------
+ master_lpt | bad lpt pos in | fsck success, fs content is
+ | master nodes. | not changed.
+ -------------------------------------------------------------------------
+ master_tnc | bad tnc pos in | fsck success, fs content is
+ | master nodes. | not changed.
+ -------------------------------------------------------------------------
+ master_total_dead | bad total_dead in | fsck success, fs content is
+ | master nodes. | not changed.
+ -------------------------------------------------------------------------
+ master_total_dirty | bad total_dirty in | fsck success, fs content is
+ | master nodes. | not changed.
+ -------------------------------------------------------------------------
+ master_total_free | bad total_free in | fsck success, fs content is
+ | master nodes. | not changed.
+ -------------------------------------------------------------------------
+ journal_log | corrupted log area. | fsck success, fs content is
+ | | not changed.
+ -------------------------------------------------------------------------
+ journal_bud | corrupted bud area. | fsck success, file data is
+ | | lost.
+ -------------------------------------------------------------------------
+ orphan_node | bad orphan node. | fsck success, file is
+ | | deleted as expected.
+ -------------------------------------------------------------------------
+ lpt_dirty | bad dirty in pnode. | fsck success, fs content is
+ | | not changed.
+ -------------------------------------------------------------------------
+ lpt_flags | bad flags in pnode | fsck success, fs content is
+ | (eg. index). | not changed.
+ -------------------------------------------------------------------------
+ lpt_free | bad free in pnode. | fsck success, fs content is
+ | | not changed.
+ -------------------------------------------------------------------------
+ lpt_pos | bad pos in nnode. | fsck success, fs content is
+ | | not changed.
+ -------------------------------------------------------------------------
+ ltab_dirty | bad dirty in lprops | fsck success, fs content is
+ | table. | not changed.
+ -------------------------------------------------------------------------
+ ltab_free | bad free in lprops | fsck success, fs content is
+ | table. | not changed.
+ -------------------------------------------------------------------------
+ index_size | bad index size in | fsck success, fs content is
+ | master nodes. | not changed.
+ -------------------------------------------------------------------------
+ tnc_lv0_key | bad key in lv0 | fsck success, fs content is
+ | znode. | not changed.
+ -------------------------------------------------------------------------
+ tnc_lv0_len | bad len in lv0 | fsck success, fs content is
+ | znode. | not changed.
+ -------------------------------------------------------------------------
+ tnc_lv0_pos | bad pos in lv0 | fsck success, fs content is
+ | znode. | not changed.
+ -------------------------------------------------------------------------
+ tnc_noleaf_key | bad key in non-leaf | fsck success, fs content is
+ | znode. | not changed.
+ -------------------------------------------------------------------------
+ tnc_noleaf_len | bad len in non-leaf | fsck success, fs content is
+ | znode. | not changed.
+ -------------------------------------------------------------------------
+ tnc_noleaf_pos | bad pos in non-leaf | fsck success, fs content is
+ | znode. | not changed.
+ -------------------------------------------------------------------------
+ corrupted_data_leb | corrupted data leb. | fsck success, partial data of
+ | | file is lost.
+ -------------------------------------------------------------------------
+ corrupted_idx_leb | corrupted index leb.| fsck success, fs content is
+ | | not changed.
+ -------------------------------------------------------------------------
+ inode_data | bad data node. | fsck success, file content
+ | | is changed, other files are
+ | | not changed.
+ -------------------------------------------------------------------------
+ inode_mode | bad inode mode for | fsck success, file is
+ | file. | dropped, other files are not
+ | | changed.
+ -------------------------------------------------------------------------
+ inode_nlink | wrong nlink for | fsck success, nlink is
+ | file. | corrected, fs content is not
+ | | changed.
+ -------------------------------------------------------------------------
+ inode_size | wrong inode size | fsck success, inode size is
+ | for file. | corrected, fs content is not
+ | | changed.
+ -------------------------------------------------------------------------
+ inode_xcnt | wrong inode | fsck success, xattr_cnt is
+ | xattr_cnt for file. | corrected, fs content is not
+ | | changed.
+ -------------------------------------------------------------------------
+ soft_link_inode_mode| bad inode mode for | fsck success, soft link
+ | solf link file. | file is dropped, other files
+ | | are not changed.
+ -------------------------------------------------------------------------
+ soft_link_data_len | bad inode data_len | fsck success, soft link
+ | for solt link file. | file is dropped, other files
+ | | are not changed.
+ -------------------------------------------------------------------------
+ dentry_key | bad dentry key for | fsck success, dentry is
+ | file. | removed, other files are
+ | | not changed.
+ -------------------------------------------------------------------------
+ dentry_nlen | inconsistent nlen | fsck success, dentry is
+ | and name in dentry | removed, other files are
+ | for file. | not changed.
+ -------------------------------------------------------------------------
+ dentry_type | inconsistent type | fsck success, dentry is
+ | between dentry and | removed, other files are
+ | inode for file. | not changed.
+ -------------------------------------------------------------------------
+ xinode_flags | lost UBIFS_XATTR_FL | fsck success, xattr is
+ | in xattr inode | removed, other files are
+ | flags for file. | not changed.
+ -------------------------------------------------------------------------
+ xinode_key | bad xattr inode key | fsck success, xattr is
+ | for file. | removed, other files are
+ | | not changed.
+ -------------------------------------------------------------------------
+ xinode_mode | bad xattr inode | fsck success, xattr is
+ | mode for file. | removed, other files are
+ | | not changed.
+ -------------------------------------------------------------------------
+ xentry_key | bad xattr entry key | fsck success, xattr is
+ | for file. | removed, other files are
+ | | not changed.
+ -------------------------------------------------------------------------
+ xentry_nlen | inconsistent nlen | fsck success, xattr is
+ | and name in xattr | removed, other files are
+ | entry for file. | not changed.
+ -------------------------------------------------------------------------
+ xentry_type | inconsistent type | fsck success, xattr is
+ | between xattr entry | removed, other files are
+ | and xattr inode for | not changed.
+ | file. |
+ -------------------------------------------------------------------------
+ xent_host | the xattr's host | fsck success, file, hard
+ | is a xattr too, the | link and soft link are
+ | flag of corrupt_file| dropped, other files are
+ | inode is modified. | not changed.
+ -------------------------------------------------------------------------
+ dir_many_dentry | dir has too many | fsck success, hard link is
+ | dentries, the dentry| dropped, other files are not
+ | of hard link is | changed.
+ | modified. |
+ -------------------------------------------------------------------------
+ dir_lost | bad dentry for dir. | fsck success, the 'file' is
+ | | recovered under lost+found,
+ | | left files under dir are
+ | | removed, other files are not
+ | | changed.
+ -------------------------------------------------------------------------
+ dir_lost_duplicated | bad inode for dir, | fsck success, the 'file' is
+ | there is a file | recovered with INO_<inum>_1
+ | under lost+found, | under lost+found, left files
+ | which named with the| under dir are removed, other
+ | inum of the 'file'. | files are not changed.
+ -------------------------------------------------------------------------
+ dir_lost_not_recover| bad inode for dir, | fsck success, all files
+ | lost+found is a | under dir are removed,
+ | regular file and | other files are not changed.
+ | exists under root |
+ | dir. |
+ -------------------------------------------------------------------------
+ root_dir | bad '/'. | fsck success, create new
+ | | root dir('/'). All regular
+ | | files are reocovered under
+ | | lost+found, other files are
+ | | removed.
+ -------------------------------------------------------------------------
+ empty_tnc | all files have bad | fsck success, fs content
+ | inode. | becomes empty.
+ =========================================================================
+
+ There is one testcase for mkfs.ubifs on encryption/non-encryption
+ situations:
+ 1) build_fs_from_dir: Initialize UBIFS image from a given directory, then
+ check whether the fs content in mounted UBIFS is consistent with the
+ original directory. Both UBI volume and file are chosen as storage
+ mediums to test. This testcase mainly ensures that mkfs.ubifs can
+ format an UBIFS image as user expected.
+
+ Dependence
+ ----------
+ kernel configs:
+ CONFIG_MTD_NAND_NANDSIM=m
+ CONFIG_MTD_MTDRAM=m
+ CONFIG_MTD_UBI=m
+ 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
+
+ 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_fsck_mount.sh
+ ./random_corrupted_fsck.sh
+ ./cycle_mount_fsck_check.sh
+ ./build_fs_from_dir.sh
+ Run all cases: sh $INSTALL_DIR/libexec/mtd-utils/ubifs_tools_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=218924
+ [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
--
2.13.6
More information about the linux-mtd
mailing list