From 09bba903b5e99296c7b8072f9ff2b11458bdbfd3 Mon Sep 17 00:00:00 2001 From: Artem Bityutskiy Date: Sun, 15 Jul 2012 17:03:42 +0300 Subject: [PATCH] UBIFS FAQ: update information about UBIFS debugging Signed-off-by: Artem Bityutskiy --- faq/ubifs.xml | 197 ++++++++++++++++++++++++-------------------------- 1 file changed, 93 insertions(+), 104 deletions(-) diff --git a/faq/ubifs.xml b/faq/ubifs.xml index c510400..ff4e36c 100644 --- a/faq/ubifs.xml +++ b/faq/ubifs.xml @@ -1201,98 +1201,99 @@ a standard PC with the nandsim NAND simulator. Please, refer the available fake MTD devices. -

Enable UBIFS debugging support

- -

Enable UBIFS debugging support in the configuration menu -(the "UBIFS debugging support" check-box). This will make sure that -assertions, debugging messages, self-checks and test modes are compiled-in. -The assertions will be enabled, but messages, self-checks and test modes -will be disabled by default. This option will also make many error messages -to be more verbose (e.g., include flash dumps). This option should not slow -down UBIFS, so it is recommended to always have it switched on, unless you -are very concerned about UBIFS code size.

- -

Debugging messages

Sometimes it is necessary to make UBIFS print about what it is doing. You may -enable various UBIFS debugging messages using the debug_msgs -UBIFS module parameter, or using the ubifs.debug_msgs kernel boot -parameter if you have UBIFS compiled in. Alternatively, the same can be -achieved by changing the /sys/module/ubifs/parameters/debug_tsts -file.

- -

The debug_msgs option is a bit-mask which controls which message -type has to be printed. You can combine the message types arbitrarily. The -following message types are supported:

+enable various UBIFS debugging messages using the "dynamic debug" Linux kernel +infrastructure (you should have it enabled by selecting the +CONFIG_DYNAMIC_DEBUG kernel configuration option). Please, refer +the Documentation/dynamic-debug-howto.txt file in the Linux kernel +sources tree for details, but here we only provide some useful recepies.

+

In the below table we use the fact that UBIFS prefixes all debugging messages +with "UBIFS DBG", which is followed by the subsystem name (see +fs/ubifs/debug.h).

- + + + + + - + - + - + - + - + - + - + - + - + - + - + - + - +
Message TypeValueMagic string
All messages (very noisy)format "UBIFS DBG" +pf'
General messages1format "UBIFS DBG gen" +pf'
Journal messages2format "UBIFS DBG jnl" +pf'
Mount messages4format "UBIFS DBG mnt" +pf'
Commit messages8format "UBIFS DBG cmt" +pf'
LEB search messages16format "UBIFS DBG find" +pf'
Budgeting messages32format "UBIFS DBG budg" +pf'
Garbage collection messages64format "UBIFS DBG gc" +pf'
Tree Node Cache (TNC) messages128format "UBIFS DBG tnc" +pf'
LEB properties (lprops) messages256format "UBIFS DBG lp" +pf'
Input/output messages512format "UBIFS DBG io" +pf'
Log messages1024format "UBIFS DBG log" +pf'
Scan messages2048format "UBIFS DBG scan" +pf'
Recovery messages4096format "UBIFS DBG rcvry" +pf'
-

E.g., "echo 4097 > /sys/module/ubifs/parameters/debug_tsts" -enables general and recovery messages.

+

To enable the debugging messages you should just write the magic string to +the /sys/kernel/debug/dynamic_debug/control file (granted your +debugfs is mounted at /sys/kernel/debug):

+ +
+echo 'format "UBIFS DBG" +pf' > /sys/kernel/debug/dynamic_debug/control
+
+ +

If you are debugging an issue which happens boot time, you can pass the +magic string with the ddebug_query kernel boot parameter (and +please, do not forget to add the ignore_loglevel if you are +relying on your default console output).

UBIFS may print huge amount of debugging messages and slow down your system considerably. You might also end up losing them if your ring buffer is not -large enough. This section explains -how to make the ring buffer larger.

+large enough. Use the log_buf_len= kernel boot parameter to make +the ring buffer larger (e.g., log_buf_len=64M).

Extra self-checks

@@ -1302,72 +1303,77 @@ very useful for debugging or testing. However, the self-checks are very expensive and slow down UBIFS a lot. We recommend to use them only while hunting bugs or testing UBIFS changes.

-

Similarly to debugging messages, the self-checks can be switched on -using the debug_chks UBIFS module parameter or the -/sys/module/ubifs/parameters/debug_chks file. The -debug_chks option is a bit-mask which selects the check -types to be enabled.

+

If your debugfs is mounted at /sys/kernel/debug, then you +should have global self-check switches at /sys/kernel/debug/ubifs +(affect all mounted file-systems and available even when you do not have any +file-system mounted) and per-file-system switches at +/sys/kernel/debug/ubifs/ubiX_Y, where X is the +mounted UBI device number and Y is the mounted volume ID. E.g., +when I mount /dev/ubi0_1, I have the following:

+ +
+$ cd /sys/kernel/debug/ubifs
+$ ls
+chk_fs  chk_general  chk_index  chk_lprops  chk_orphans  tst_recovery  ubi0_0
+$ ls ubi0_0/
+chk_fs       chk_index   chk_orphans  dump_lprops  ro_error
+chk_general  chk_lprops  dump_budg    dump_tnc     tst_recovery
+
+ +

The self-check files start with "chk_" which follows by the UBIFS sub-system +name where the self-checks will be enabled. The below table provides some more +details.

- - - - - - - - - + - - + + - - + + - - + + - - + + - - + +
Check typeValue
General checks1
Check Tree Node Cache (TNC)2File name
Check indexing tree size4General checks. Check correctness of inode size and link count, + buds accounting and node lists sorting, lprops categories, etc. + Also forces the "in-the-gaps" commit method whenever possible + (normally this method is used very rarely as the last resort method + when there is no enough free space to commit the normal way).chk_general
Check orphan area8Index checks. Quite heavy checks of index correctness.chk_index
Check old indexing tree16Orphans checks.chk_orphans
Check LEB properties (lprops)32LEB properties (lprops) checks.chk_lprops
Check leaf nodes and inodes64Full file-system data checks on every commit.chk_fs
-

E.g., "echo 3 > /sys/module/ubifs/parameters/debug_chks" enables -general checks and TNC checks. But for testing, it is better to just enable -all checks: "echo 127 > /sys/module/ubifs/parameters/debug_chks".

-

Test modes

+

Power-cut recovery testing

-

UBIFS currently supports 2 test modes:

- +

UBIFS suppors the power-cut emulation infrastructure which emulates a +power-cut at random points. When a power-cut is emulated, UBIFS switches to +read-only mode and disallows any further write to the UBIFS volume, thus +emulating a power cut. The main idea of this mode is to emulate power cuts in +"interesting" places, e.g., when changing the log, or the orphans area. Indeed, +real power-cuts testing mostly interrupts UBIFS when it is writing data to the +journal.

+ +

Use the tst_recovery debugfs file to enable the power-cut +recovery testing mode. Alternatively, you may switch UBIFS to R/O mode using +the ro_error file.

+

The integck test program (part of the mtd-utils +repository) is aware of UBIFS power cut recovery testing mode and can be used +for UBIFS power-cut testing.

How do I send an UBIFS bug report?

@@ -1392,13 +1398,6 @@ all checks: "echo 127 > /sys/module/ubifs/parameters/debug_chks".make sure you have compiled the kernel symbols in (CONFIG_KALLSYMS_ALL=y in .config); -
  • mark the Enable debugging support check-box in the UBIFS - kernel configuration menu (CONFIG_UBIFS_FS_DEBUG=y in - .config); this option will make UBIFS print more - informative error messages; note, you should enable UBIFS - debugging, not UBI debugging - distinguish between UBI and UBIFS please, - they are different things;
    • -
  • include all the messages UBIFS prints, not only those you see at the console, but also those you see when running dmesg; or before running your UBIFS test, which reproduces the error, just @@ -1407,26 +1406,16 @@ all checks: "echo 127 > /sys/module/ubifs/parameters/debug_chks".ignore_loglevel option, in which makes the kernel print all messages to the console unconditionally; this section contains - some more information about how the messages can be collected.
    • - -
  • explicitly tell about whether you did any checking as described in - the previous list of "actions before sending a bug-report" (running MTD - tests, enabling UBIFS extra self-checks; and tell the results; if you - saw any errors/warnings, describe them and include all corresponding - prints from tests / UBIFS / etc;
    • - -
  • provide UBI and UBIFS configuration from your - .config file, or just attach whole file;
    • + some more information about how the messages can be collected;
  • describe your flash device, attach the "mtdinfo -a" output (or the less useful "cat /proc/mtd" output);
  • specify which kernel version you are using; if your kernel is not the latest one, please, explicitly tell whether you updated UBIFS by - pulling one of the back-port trees or not; if you did not, you will - probably be asked to do this, depending on the problem;
    • + pulling one of the back-port trees or not; -
  • describe how the problem can be reproduced;
    • +
  • describe how the problem can be reproduced.

    • The bugreport should be sent to the -- 2.49.0