diff options
| -rw-r--r-- | README.md | 36 | ||||
| -rw-r--r-- | utils/lib/loopdev.c | 14 | ||||
| -rw-r--r-- | utils/sys-utils/xlosetup.8 | 2 |
3 files changed, 44 insertions, 8 deletions
@@ -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 |