| Message ID | 20221209142331.26395-2-sergei.shtepa@veeam.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | blksnap - block devices snapshots module | expand |
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.
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
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 <sergei.shtepa@veeam.com> --- Documentation/block/blkfilter.rst | 50 +++++++++++++++++++++++++++++++ Documentation/block/index.rst | 1 + 2 files changed, 51 insertions(+) create mode 100644 Documentation/block/blkfilter.rst