From patchwork Fri Jun 9 11:58:48 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sergei Shtepa X-Patchwork-Id: 105592 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a59:994d:0:b0:3d9:f83d:47d9 with SMTP id k13csp905573vqr; Fri, 9 Jun 2023 05:22:32 -0700 (PDT) X-Google-Smtp-Source: ACHHUZ57vByo+cvpWpHKOTHlaR7i5Geax8+7SyB8eyyCP7/WiMSl8BCaKQAkiOxk8qoq/m6z/DPg X-Received: by 2002:a17:902:fa8f:b0:1b0:3d03:4179 with SMTP id lc15-20020a170902fa8f00b001b03d034179mr1614990plb.6.1686313352149; Fri, 09 Jun 2023 05:22:32 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1686313352; cv=none; d=google.com; s=arc-20160816; b=M9KkxMGMcSj1lMpD4P1K4Ewn2sqmWynNsgo+ET8sFo2Oxb3GCq+GW6gHO8J7OFVbQi YwW5n2AH/L1AU0Ms4CVhyNlUZjW0NNUAwKvYzFMcaByzdMr6Og7h87aNG0T1TuKOZcMt OTe3y5WbA8SXNC7lNhfWGp+iA9Ohn32LFVSGIAT7bd8u/vk+dlxwf4ao79gpoxuBBhpo LdRC0xP8YwtCwWdQ+ICfqBj8k72HnE/A3t0laEnQGWFszR+IEqubM6zoPB8v4PnLQZPe Lc+8CFS1eOSHEkJun9HdgRNXa/GQCNKLyBGMThBt8uEfzpUXHoJCnbd8aIXHzEVQFPyq vUDw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:content-transfer-encoding:mime-version :message-id:date:subject:cc:to:from:dkim-signature; bh=xI5U7I017OidC54JE6H4lbxHIRF0RMUuN/RqLqBQZp8=; b=aqe9CGDJN/D6HJa7G8Q8Mf5FaLVRhh6f6IOA/lXjIK6suaGPPfPBSn1BfffhmIppi1 KuaeUcXJ86H6SzyGbYFBrFh/q4CqnjeHyEooNqNpy4fUsDBG67OZQ45YmcC4JlvQsg7J 0NZQXbIxoDvOJyIcPZnucRIugYF1BGsIpEM5t6XW/fsPyI6ltCCiPQeMtnOvG2QTDOnz h5tnwu3P8mXyhIPi5sEoSP5XpO2Fazeoa64D4bf+CTnQroVGVion867LqhYVAGsD8pRG 6qzYat7+OVPmc/RCzJdcLPcKapHEDtwLiAqV6CFnOJV0YDMEk4kMubo+hvScQJCkik1i ITcg== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@veeam.com header.s=mx1-2022 header.b=Abehoq5o; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=REJECT sp=REJECT dis=NONE) header.from=veeam.com Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id u20-20020a170903305400b001ae645b8d11si2630517pla.119.2023.06.09.05.22.15; Fri, 09 Jun 2023 05:22:32 -0700 (PDT) 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; Authentication-Results: mx.google.com; dkim=pass header.i=@veeam.com header.s=mx1-2022 header.b=Abehoq5o; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=REJECT sp=REJECT dis=NONE) header.from=veeam.com Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S240288AbjFIMQ7 (ORCPT + 99 others); Fri, 9 Jun 2023 08:16:59 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:59730 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S230076AbjFIMQy (ORCPT ); Fri, 9 Jun 2023 08:16:54 -0400 Received: from mx1.veeam.com (mx1.veeam.com [216.253.77.21]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 010FF185; Fri, 9 Jun 2023 05:16:51 -0700 (PDT) Received: from mail.veeam.com (prgmbx01.amust.local [172.24.128.102]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.veeam.com (Postfix) with ESMTPS id CA86D42522; Fri, 9 Jun 2023 07:59:17 -0400 (EDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=veeam.com; s=mx1-2022; t=1686311958; bh=xI5U7I017OidC54JE6H4lbxHIRF0RMUuN/RqLqBQZp8=; h=From:To:CC:Subject:Date:From; b=Abehoq5oDSasqmcnt/zZf3kO3zp7A+lTkaJymLCxpNoHkBNeeshcfI7Gtg11AVlWv +YoNNyiEMjKcgQZ3Lsc5BLwllTFQXlmSWF/DhEd+d6GZ8Y9lKfzBEQxRxuTxmejqkP xiy/v1jL7YvyH3ppkZ2nSyhwCcXxZKZ4QCzy9rKJjW7E76wwvwL/vlXsyssApFe9Bg ehJAq9BcvN5SY9Mf0VB8DZ+s9R53VhrFXRkqflUFYNn1uK6jH8QrmpcDwsjyAKt42X 9Xjw/xXhELl/eLWJtzTRzAhWKILDRMQZGKmcrrLPwOv534N6/ob8MTXAS2fOpInub6 1i8YTLCZ7H0VQ== Received: from ssh-deb10-ssd-vb.amust.local (172.24.10.107) by prgmbx01.amust.local (172.24.128.102) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.2.1118.26; Fri, 9 Jun 2023 13:59:15 +0200 From: Sergei Shtepa To: , , , CC: , , , , , , , , , , , , , Bagas Sanjaya Subject: [PATCH v4 01/11] documentation: Block Device Filtering Mechanism Date: Fri, 9 Jun 2023 13:58:48 +0200 Message-ID: <20230609115858.4737-1-sergei.shtepa@veeam.com> X-Mailer: git-send-email 2.20.1 MIME-Version: 1.0 X-Originating-IP: [172.24.10.107] X-ClientProxiedBy: prgmbx02.amust.local (172.24.128.103) To prgmbx01.amust.local (172.24.128.102) X-EsetResult: clean, is OK X-EsetId: 37303A2924031554627C6B X-Veeam-MMEX: True X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,SPF_HELO_NONE, SPF_PASS,T_SCC_BODY_TEXT_LINE,URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1768227709150276574?= X-GMAIL-MSGID: =?utf-8?q?1768227709150276574?= 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 Reviewed-by: Bagas Sanjaya Signed-off-by: Sergei Shtepa Reported-by: Randy Dunlap Signed-off-by: Sergei Shtepa --- Documentation/block/blkfilter.rst | 64 +++++++++++++++++++++++++++++++ Documentation/block/index.rst | 1 + MAINTAINERS | 6 +++ 3 files changed, 71 insertions(+) create mode 100644 Documentation/block/blkfilter.rst -- 2.20.1 diff --git a/Documentation/block/blkfilter.rst b/Documentation/block/blkfilter.rst new file mode 100644 index 000000000000..555625789244 --- /dev/null +++ b/Documentation/block/blkfilter.rst @@ -0,0 +1,64 @@ +.. 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 none of the in-tree kernel modules 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 stack. + +It supports attaching one filter to one block device, because there is only +one filter implementation in the kernel yet. +See Documentation/block/blksnap.rst. + +Design +====== + +The block device filtering mechanism provides registration and unregistration +for filter operations. The struct blkfilter_operations contains a pointer to +the callback functions for the filter. After registering the filter operations, +filter can be managed using block device ioctl BLKFILTER_ATTACH, +BLKFILTER_DETACH and BLKFILTER_CTL. + +When the filter is attached, the 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 filter can be implemented as a loadable module. In this case, the filter +module cannot be unloaded while the filter is attached to at least one of the +block devices. + +Interface description +===================== + +The ioctl BLKFILTER_ATTACH and BLKFILTER_DETACH use structure blkfilter_name. +It allows to attach a filter to a block device or detach it. + +The ioctl BLKFILTER_CTL use structure blkfilter_ctl. It allows to send a +filter-specific command. + +.. kernel-doc:: include/uapi/linux/blk-filter.h + +To register in the system, the filter creates its own account, which contains +callback functions, unique filter name and module owner. This filter account is +used by the registration functions. + +.. kernel-doc:: include/linux/blk-filter.h + +.. kernel-doc:: block/blk-filter.c + :export: diff --git a/Documentation/block/index.rst b/Documentation/block/index.rst index 9fea696f9daa..e9712f72cd6d 100644 --- a/Documentation/block/index.rst +++ b/Documentation/block/index.rst @@ -10,6 +10,7 @@ Block bfq-iosched biovecs blk-mq + blkfilter cmdline-partition data-integrity deadline-iosched diff --git a/MAINTAINERS b/MAINTAINERS index 250518fc70ff..f85f21487364 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -3583,6 +3583,12 @@ M: Jan-Simon Moeller S: Maintained F: drivers/leds/leds-blinkm.c +BLOCK DEVICE FILTERING MECHANISM +M: Sergei Shtepa +L: linux-block@vger.kernel.org +S: Supported +F: Documentation/block/blkfilter.rst + BLOCK LAYER M: Jens Axboe L: linux-block@vger.kernel.org