The document contains:
* Describes the purpose of the mechanism
* A little historical background on the capabilities of handling I/O
units of the Linux kernel
* Brief description of the design
* Reference to interface description
Signed-off-by: Sergei Shtepa <[email protected]>
---
Documentation/block/blkfilter.rst | 50 +++++++++++++++++++++++++++++++
Documentation/block/index.rst | 1 +
2 files changed, 51 insertions(+)
create mode 100644 Documentation/block/blkfilter.rst
diff --git a/Documentation/block/blkfilter.rst b/Documentation/block/blkfilter.rst
new file mode 100644
index 000000000000..3482e16c1964
--- /dev/null
+++ b/Documentation/block/blkfilter.rst
@@ -0,0 +1,50 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+================================
+Block Device Filtering Mechanism
+================================
+
+The block device filtering mechanism is an API that allows to attach block
+device filters. Block device filters allow perform additional processing
+for I/O units.
+
+Introduction
+============
+
+The idea of handling I/O units on block devices is not new. Back in the
+2.6 kernel, there was an undocumented possibility of handling I/O units
+by substituting the make_request_fn() function, which belonged to the
+request_queue structure. But no kernel module used this feature, and it
+was eliminated in the 5.10 kernel.
+
+The block device filtering mechanism returns the ability to handle I/O units.
+It is possible to safely attach filter to a block device "on the fly" without
+changing the structure of block devices.
+
+It supports attaching one filter to one block device, because there is only
+one filter implementation in the kernel.
+See Documentation/block/blksnap.rst.
+
+Design
+======
+
+The block device filtering mechanism provides functions for attaching and
+detaching the filter. The filter is a structure with a reference counter
+and callback functions.
+
+The submit_bio_cb() callback function is called for each I/O unit for a block
+device, providing I/O unit filtering. Depending on the result of filtering
+the I/O unit, it can either be passed for subsequent processing by the block
+layer, or skipped.
+
+The reference counter allows to control the filter lifetime. When the reference
+count is reduced to zero, the release_cb() callback function is called to
+release the filter. This allows the filter to be released when the block
+device is disconnected.
+
+Interface description
+=====================
+.. kernel-doc:: include/linux/blkdev.h
+ :functions: bdev_filter_operations bdev_filter bdev_filter_init bdev_filter_get bdev_filter_put
+.. kernel-doc:: block/bdev.c
+ :functions: bdev_filter_attach bdev_filter_detach
diff --git a/Documentation/block/index.rst b/Documentation/block/index.rst
index c4c73db748a8..bef6de22d651 100644
--- a/Documentation/block/index.rst
+++ b/Documentation/block/index.rst
@@ -10,6 +10,7 @@ Block
bfq-iosched
biovecs
blk-mq
+ blkfilter
capability
cmdline-partition
data-integrity
--
2.20.1
On Fri, Dec 09, 2022 at 03:23:11PM +0100, Sergei Shtepa wrote:
> The document contains:
> * Describes the purpose of the mechanism
> * A little historical background on the capabilities of handling I/O
> units of the Linux kernel
> * Brief description of the design
> * Reference to interface description
>
The patch subject should be "Documentation: document block device
filtering"
Also, write the patch description in imperative mood.
> diff --git a/Documentation/block/blkfilter.rst b/Documentation/block/blkfilter.rst
> new file mode 100644
> index 000000000000..3482e16c1964
> --- /dev/null
> +++ b/Documentation/block/blkfilter.rst
> @@ -0,0 +1,50 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +================================
> +Block Device Filtering Mechanism
> +================================
> +
> +The block device filtering mechanism is an API that allows to attach block
> +device filters. Block device filters allow perform additional processing
> +for I/O units.
> +
> +Introduction
> +============
> +
> +The idea of handling I/O units on block devices is not new. Back in the
> +2.6 kernel, there was an undocumented possibility of handling I/O units
> +by substituting the make_request_fn() function, which belonged to the
> +request_queue structure. But no kernel module used this feature, and it
> +was eliminated in the 5.10 kernel.
> +
> +The block device filtering mechanism returns the ability to handle I/O units.
> +It is possible to safely attach filter to a block device "on the fly" without
> +changing the structure of block devices.
> +
> +It supports attaching one filter to one block device, because there is only
> +one filter implementation in the kernel.
> +See Documentation/block/blksnap.rst.
> +
> +Design
> +======
> +
> +The block device filtering mechanism provides functions for attaching and
> +detaching the filter. The filter is a structure with a reference counter
> +and callback functions.
> +
> +The submit_bio_cb() callback function is called for each I/O unit for a block
> +device, providing I/O unit filtering. Depending on the result of filtering
> +the I/O unit, it can either be passed for subsequent processing by the block
> +layer, or skipped.
> +
> +The reference counter allows to control the filter lifetime. When the reference
> +count is reduced to zero, the release_cb() callback function is called to
> +release the filter. This allows the filter to be released when the block
> +device is disconnected.
> +
> +Interface description
> +=====================
> +.. kernel-doc:: include/linux/blkdev.h
> + :functions: bdev_filter_operations bdev_filter bdev_filter_init bdev_filter_get bdev_filter_put
> +.. kernel-doc:: block/bdev.c
> + :functions: bdev_filter_attach bdev_filter_detach
What about the wording below instead?
---- >8 ----
diff --git a/Documentation/block/blkfilter.rst b/Documentation/block/blkfilter.rst
index 3482e16c1964e6..fe2a4151c38fde 100644
--- a/Documentation/block/blkfilter.rst
+++ b/Documentation/block/blkfilter.rst
@@ -5,7 +5,7 @@ Block Device Filtering Mechanism
================================
The block device filtering mechanism is an API that allows to attach block
-device filters. Block device filters allow perform additional processing
+device filters. Block device filters allow performing additional processing
for I/O units.
Introduction
@@ -14,16 +14,16 @@ Introduction
The idea of handling I/O units on block devices is not new. Back in the
2.6 kernel, there was an undocumented possibility of handling I/O units
by substituting the make_request_fn() function, which belonged to the
-request_queue structure. But no kernel module used this feature, and it
-was eliminated in the 5.10 kernel.
+request_queue structure. But no kernel module used this feature, which was
+the reason why it was removed in the 5.10 kernel.
-The block device filtering mechanism returns the ability to handle I/O units.
-It is possible to safely attach filter to a block device "on the fly" without
+With block device filtering, the ability to handling I/O units is back. It is
+now possible to safely attaching filter to a block device "on the fly" without
changing the structure of block devices.
-It supports attaching one filter to one block device, because there is only
-one filter implementation in the kernel.
-See Documentation/block/blksnap.rst.
+It supports attaching a filter to a block device, due to there is only
+one filter implementation in the kernel. See Documentation/block/blksnap.rst
+for details.
Design
======
@@ -33,9 +33,9 @@ detaching the filter. The filter is a structure with a reference counter
and callback functions.
The submit_bio_cb() callback function is called for each I/O unit for a block
-device, providing I/O unit filtering. Depending on the result of filtering
-the I/O unit, it can either be passed for subsequent processing by the block
-layer, or skipped.
+device, providing I/O unit filtering. Depending on filtering result, it can
+either be passed for subsequent processing by the block
+layer, or be skipped.
The reference counter allows to control the filter lifetime. When the reference
count is reduced to zero, the release_cb() callback function is called to
Thanks.
--
An old man doll... just what I always wanted! - Clara