summaryrefslogtreecommitdiffstats
path: root/README.md
blob: 28b2a255b1dee0b258c31b4ab50ab5f8cba509ca (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215

xloop - eXtended loop device

The eXtended loop (xloop) device provides a subsystem for the Linux kernel to register custom file format drivers. Those file format drivers enable the possibility to write and read file formats in the kernel space rather than in the user space.

This repository contains the source code for the xloop Linux kernel modules

  • xloop: eXtended loop device with file format subsystem
  • xloop_file_format_raw: file format subsystem driver for RAW files
  • xloop_file_format_qcow: file format subsystem driver for QCOW files

and the user space utility xlosetup to configure xloop devices. The xloop Linux kernel modules can be built for the following Linux kernel versions and Linux distributions:

  • Archlinux with Linux kernel 5.10.x or 5.4.x
  • Raspberry Pi OS with Linux kernel 5.4.x
  • Ubuntu 20.04 with Linux kernel 5.4.x
  • Ubuntu 18.04 with Linux kernel 4.19.x
  • CentOS 8 with Linux kernel 4.18.x
  • AlmaLinux 8 with Linux kernel 4.18.x

Build

Preliminaries

A build of the xloop Linux kernel modules and the xlosetup utility requires the installation of the following build tools and libraries under your supported Linux distribution.

Archlinux with Linux kernel 5.10.x or 5.4.x

pacman -S git \
          make \
          cmake \
          gcc \
          clang \
          linux-headers \  # or linux-lts-headers
          libcap \  # required only in Debug build configuration
          dpkg \
          rpm-tools

Raspberry Pi OS with Linux kernel 5.4.x

apt-get install git \
                make \
                cmake \
                gcc \
                clang-format \
                raspberrypi-kernel-headers \
                libcap-dev \  # required only in Debug build configuration
                rpm

Ubuntu 20.04 with Linux kernel 5.4.x

apt-get install git \
                make \
                cmake \
                gcc \
                clang-format \
                linux-headers-generic \
                libcap-dev \  # required only in Debug build configuration
                rpm

Ubuntu 18.04 with Linux kernel 4.19.x

apt-get install git \
                make \
                cmake \
                gcc \
                clang-format \
                linux-headers-generic \
                libcap-dev \  # required only in Debug build configuration
                rpm

CentOS 8 with Linux kernel 4.18.x

yum install git \
            make \
            cmake \
            gcc \
            clang-tools-extra \
            kernel-devel \
            elfutils-libelf-devel \
            libcap-devel \  # required only in Debug build configuration
            rpm-build

AlmaLinux 8 with Linux kernel 4.18.x

yum install git \
            make \
            cmake \
            gcc \
            clang-tools-extra \
            kernel-devel \
            elfutils-libelf-devel \
            libcap-devel \  # required only in Debug build configuration
            rpm-build

Preparation

Before a build takes place, you should create a build directory inside the root folder of the repository. After that, change your working directory to that new directory as follows:

mkdir build
cd build

Configuration

A build of the xloop Linux kernel modules and the xlosetup utility can be configured and customized by the following configuration variables (CMake cache entries):

Variable Type Values Default value Description
CMAKE_BUILD_TYPE STRING {Debug, Release} Debug Build configuration of the xloop project.
KERNEL_BUILD_DIR PATH {a .. z, A .. Z, /, _, -} /lib/modules/uname -r/build Path to Linux kernel modules to compile against.
KERNEL_INSTALL_DIR PATH {a .. z, A .. Z, /, _, -} /lib/modules/uname -r/extra Path to install Linux kernel modules.
KERNEL_SCRIPTS_DIR PATH {a .. z, A .. Z, /, _, -} /lib/modules/uname -r/build/scripts Path to Linux kernel scripts directory.
XLOOP_MAJOR NUMBER {0 .. 255} 120 Major number for xloop devices.
XLOOP_CTRL_MINOR NUMBER {0 .. 255} 15 Minor number for the xloop-control device.
BLK_DEV_XLOOP_MIN_COUNT NUMBER {0 .. 255} 8 Number of xloop devices to pre-create at init time.

A value from the range of appropriate values can be assigend to each configuration variable by executing CMake once with the following command pattern:

cmake -D<VARIABLE>=<VALUE> [-D ...] ../.

Debug

In the Debug build configuration, all Linux kernel modules and the utility can be built by calling make:

make

Optionally, the output files can be installed with superuser permissions on the local system using the Makefile target install:

sudo make install
sudo depmod -a

Packages

In the Release build configuration, installation packages can be built by calling the make target package:

make package

This target creates a Debian installation package (*.deb), a RPM installation package (*.rpm) and a compressed archive (*.tar.gz) containing the built xloop Linux kernel modules and the xlosetup utility executable as well as its man page and bash-completion support.

Sources

In the Release build configuration, sources can be built by calling the make target source:

make source

This target creates compressed archives (*_source.tar.gz and *_source.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:

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:

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 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:

export XLOOPDEV_DEBUG=all
export LIBSMARTCOLS_DEBUG=all

Development notes

Code style of source code files

The code style of the source code files can be checked by calling the make target lint:

make lint

If some source code files do not meet the project's code style, they can be fixed automatically by calling the make target lint-fix:

make lint-fix