Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
From:   Sergei Shtepa <sergei.shtepa@veeam.com>
To:     <axboe@kernel.dk>, <corbet@lwn.net>
CC:     <linux-block@vger.kernel.org>, <linux-doc@vger.kernel.org>,
        <linux-kernel@vger.kernel.org>,
        Sergei Shtepa <sergei.shtepa@veeam.com>
Subject: [PATCH v2 01/21] documentation, blkfilter: Block Device Filtering Mechanism
Date:   Fri, 9 Dec 2022 15:23:11 +0100
Message-ID: <20221209142331.26395-2-sergei.shtepa@veeam.com>
In-Reply-To: <20221209142331.26395-1-sergei.shtepa@veeam.com>
References: <20221209142331.26395-1-sergei.shtepa@veeam.com>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Content-Type: text/plain
Precedence: bulk

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

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