From eb4fefc56bb55b7000fd179cf397af83abb062df Mon Sep 17 00:00:00 2001
From: Manuel Bentele
Date: Mon, 12 Oct 2020 11:45:32 +0200
Subject: Added debug support for xlosetup and documented debugging in README

---
 README.md                  | 36 ++++++++++++++++++++++++++++++++++++
 utils/lib/loopdev.c        | 14 +++++++-------
 utils/sys-utils/xlosetup.8 |  2 +-
 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
-- 
cgit v1.2.3-55-g7522