summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--README.md36
-rw-r--r--utils/lib/loopdev.c14
-rw-r--r--utils/sys-utils/xlosetup.82
3 files changed, 44 insertions, 8 deletions
diff --git a/README.md b/README.md
index a1ddb86..981f667 100644
--- a/README.md
+++ b/README.md
@@ -121,3 +121,39 @@ make package_source
```
This target creates compressed archives (\*_sources.tar.gz and \*_sources.zip) containing the source code of this repository for code distribution purposes.
+
+
+## Debugging
+Debugging of the Linux kernel modules and the user space utility requires this project to be built in the `Debug` configuration.
+
+### Linux kernel modules
+The Linux kernel modules **xloop**, **xloop_file_fmt_raw** and **xloop_file_fmt_qcow** support the Linux kernel's dynamic debug feature if the Linux kernel is built with the enabled kernel configuration `CONFIG_DYNAMIC_DEBUG`. The dynamic debug feature allows the printing of customizable debug messages into the Linux kernel's message buffer.
+
+Dynamic debug for the modules can be either enabled at module initialization or during operation. At module initialization, dynamic debug can be enabled by modprobe using the "fake" module parameter `dyndbg`:
+
+```shell
+modprobe xloop dyndbg=+pflmt
+modprobe xloop_file_fmt_raw dyndbg=+pflmt
+modprobe xloop_file_fmt_qcow dyndbg=+pflmt
+```
+
+The module parameter `dyndbg` customizes the debug messages written into the Linux kernel's message buffer. The specific value `+pflmt` enables all debug messages in the source code and includes function name (`f`), line number (`l`), module name (`m`) and thread ID (`t`) for each executed debug statement from the source code.
+
+During operation, debug messages from debug statements in the code can be customized and enabled dynamically as well using the debugfs control file `<DEBUG_FS>/dynamic_debug/control` where `DEBUG_FS` is the mount point of a mounted DebugFS, eg. `/sys/kernel/debug`:
+
+```shell
+echo "module xloop +pflmt" > <DEBUG_FS>/dynamic_debug/control
+echo "module xloop_file_fmt_raw +pflmt" > <DEBUG_FS>/dynamic_debug/control
+echo "module xloop_file_fmt_qcow +pflmt" > <DEBUG_FS>/dynamic_debug/control
+```
+
+More information regarding the Linux kernel's dynamic debug feature can be found in the (https://www.kernel.org/doc/html/latest/admin-guide/dynamic-debug-howto.html)[Linux kernel documentation].
+
+
+### User space utility
+Built-in debug messages from the user space utility **xlosetup** can be enabled by setting the following environment variables before any execution of xlosetup:
+
+```shell
+export XLOOPDEV_DEBUG=all
+export LIBSMARTCOLS_DEBUG=all
+```
diff --git a/utils/lib/loopdev.c b/utils/lib/loopdev.c
index d377371..be4e486 100644
--- a/utils/lib/loopdev.c
+++ b/utils/lib/loopdev.c
@@ -48,13 +48,13 @@
static UL_DEBUG_DEFINE_MASK(loopdev);
UL_DEBUG_DEFINE_MASKNAMES(loopdev) = UL_DEBUG_EMPTY_MASKNAMES;
-#define LOOPDEV_DEBUG_INIT (1 << 1)
-#define LOOPDEV_DEBUG_CXT (1 << 2)
-#define LOOPDEV_DEBUG_ITER (1 << 3)
-#define LOOPDEV_DEBUG_SETUP (1 << 4)
+#define XLOOPDEV_DEBUG_INIT (1 << 1)
+#define XLOOPDEV_DEBUG_CXT (1 << 2)
+#define XLOOPDEV_DEBUG_ITER (1 << 3)
+#define XLOOPDEV_DEBUG_SETUP (1 << 4)
-#define DBG(m, x) __UL_DBG(loopdev, LOOPDEV_DEBUG_, m, x)
-#define ON_DBG(m, x) __UL_DBG_CALL(loopdev, LOOPDEV_DEBUG_, m, x)
+#define DBG(m, x) __UL_DBG(loopdev, XLOOPDEV_DEBUG_, m, x)
+#define ON_DBG(m, x) __UL_DBG_CALL(loopdev, XLOOPDEV_DEBUG_, m, x)
#define UL_DEBUG_CURRENT_MASK UL_DEBUG_MASK(loopdev)
#include "debugobj.h"
@@ -63,7 +63,7 @@ static void loopdev_init_debug(void)
{
if (loopdev_debug_mask)
return;
- __UL_INIT_DEBUG_FROM_ENV(loopdev, LOOPDEV_DEBUG_, 0, LOOPDEV_DEBUG);
+ __UL_INIT_DEBUG_FROM_ENV(loopdev, XLOOPDEV_DEBUG_, 0, XLOOPDEV_DEBUG);
}
/*
diff --git a/utils/sys-utils/xlosetup.8 b/utils/sys-utils/xlosetup.8
index 7dd2fa0..4e063e6 100644
--- a/utils/sys-utils/xlosetup.8
+++ b/utils/sys-utils/xlosetup.8
@@ -184,7 +184,7 @@ is not configured and 2 if an error occurred which prevented
determining the status of the device.
.SH ENVIRONMENT
-.IP LOOPDEV_DEBUG=all
+.IP XLOOPDEV_DEBUG=all
enables debug output.
.SH FILES