Re: [PATCH v2 01/21] documentation, blkfilter: Block Device Filtering Mechanism

[Bagas Sanjaya]

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

Attachment: signature.asc
Description: PGP signature