[2/5] doc: admin-guide: add loop block device documentation

Commit Message

Manuel Bentele Aug. 23, 2019, 10:56 p.m. UTC

From: Manuel Bentele <[e-mail]>

The configuration of the loop block device module with file format support
is documented in the reST kernel documentation format.

Signed-off-by: Manuel Bentele <[e-mail]>
---
 Documentation/admin-guide/blockdev/index.rst |  1 +
 Documentation/admin-guide/blockdev/loop.rst  | 74 ++++++++++++++++++++
 2 files changed, 75 insertions(+)
 create mode 100644 Documentation/admin-guide/blockdev/loop.rst

Patch

diff --git a/Documentation/admin-guide/blockdev/index.rst b/Documentation/admin-guide/blockdev/index.rst
index b903cf152091..127e921a0ccc 100644
--- a/Documentation/admin-guide/blockdev/index.rst
+++ b/Documentation/admin-guide/blockdev/index.rst
@@ -8,6 +8,7 @@  The Linux RapidIO Subsystem
    :maxdepth: 1
 
    floppy
+   loop
    nbd
    paride
    ramdisk
diff --git a/Documentation/admin-guide/blockdev/loop.rst b/Documentation/admin-guide/blockdev/loop.rst
new file mode 100644
index 000000000000..69d8172c85db
--- /dev/null
+++ b/Documentation/admin-guide/blockdev/loop.rst
@@ -0,0 +1,74 @@ 
+.. SPDX-License-Identifier: GPL-2.0
+
+Loopback Block Device
+=====================
+
+Overview
+--------
+
+The loopback device driver allows you to use a regular file as a block device.
+You can then create a file system on that block device and mount it just as you
+would mount other block devices such as hard drive partitions, CD-ROM drives or
+floppy drives. The loop devices are block special device files with major
+number 7 and typically called /dev/loop0, /dev/loop1 etc.
+
+To use the loop device, you need the losetup utility, found in the `util-linux
+package <https://www.kernel.org/pub/linux/utils/util-linux/>`_.
+
+.. note::
+	Note that this loop device has nothing to do with the loopback device \
+	used for network connections from the machine to itself.
+
+
+Parameters
+----------
+
+Kernel Command Line Parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+	max_loop
+		The number of loop block devices that get unconditionally
+		pre-created at init time. The default number is configured by
+		BLK_DEV_LOOP_MIN_COUNT. Instead of statically allocating a
+		predefined number, loop devices can be requested on-demand
+		with the /dev/loop-control interface.
+
+
+Module parameters
+~~~~~~~~~~~~~~~~~
+
+	max_part
+		Maximum number of partitions per loop device (default: 0).
+
+		If max_part is given, partition scanning is globally enabled
+		for all loop devices.
+
+	max_loop
+		Maximum number of loop devices that should be initialized
+		(default: 8). The default number is configured by
+		BLK_DEV_LOOP_MIN_COUNT.
+
+
+File format drivers
+-------------------
+
+The loopback device driver provides an interface for kernel modules to
+implement custom file formats. By default, an initialized loop device uses the
+**RAW** file format driver.
+
+.. note::
+	If you want to create and set up a new loop device with the losetup \
+	utility make sure that the suitable file format driver is loaded \
+	before.
+
+The following file format drivers are available.
+
+
+RAW
+~~~
+
+The RAW file format driver implements the binary reading and writing of a disk
+image file. It supports discarding, asynchrounous IO, flushing and cryptoloop
+support.
+
+The driver's kernel module is named *loop_file_fmt_raw*.