From patchwork Mon Jun 12 13:21:27 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sergei Shtepa X-Patchwork-Id: 106588 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a59:994d:0:b0:3d9:f83d:47d9 with SMTP id k13csp2589214vqr; Mon, 12 Jun 2023 06:29:27 -0700 (PDT) X-Google-Smtp-Source: ACHHUZ5xs1FK3aCbIv3rBsfV1EP9kr5MYz/7ihWaxrl4iZm1mSf9ALlEvUcmeJ9Jq9ikFwsYYfi3 X-Received: by 2002:a05:6a00:17a5:b0:63a:ea82:b7b7 with SMTP id s37-20020a056a0017a500b0063aea82b7b7mr11609159pfg.28.1686576567157; Mon, 12 Jun 2023 06:29:27 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1686576567; cv=none; d=google.com; s=arc-20160816; b=QtJZTg6kNgsxd9Jhb0DzUXvb6rXbTznnrl+VCdRhIVfKXI1t8niHZxNn42HfSXJJ98 /irSbaWyEqpHErZZUJqdorh7GmQixZTx9YCt9qZ2Un365ojbGMMGpFu84L9g8rziOFca cEx9HNmZ7oTeysDvAPDWKiU5/sg7bVCKJiI88VQk6BLrJAiLbMC8N6UkWmbFy7j0ypD4 7lHXbwS1QnfHr4qi/FsqEqeVfozT6ZwLizcA22/oTQaxqouOIGTDt773N5cka0YPrA98 h+D/gdT+dA6S5iO4BnCO+MGcLrw0508djoxdlql1202AkJgNHuo9F5PjQdYpPPCI0Afl tvkA== 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 :references:in-reply-to:message-id:date:subject:cc:to:from :dkim-signature; bh=ugxVl7Zf6JxnwJk4+LT20nHkkRjvyXw6j21wQSIhSbA=; b=O93sjKVPu1fNFwsLt7axq5MX+dSDaEsYOSdZb7Xh6rYuH+Lo4e2f13LgqccAm/7x51 pmWdESDk4LvSgXMEYsh9myvC4DN07Wa7Un1523dI2jlj6jvddkNhWm64EAB2m0cCzLjp OTyfUEghBeRhbMiiaeWEDpdRvagRDXE8UIWO5AXPy5oTYvkU5kCibEifQjhUU+DlnYE3 ZuGmG+3xheSpYu2saBCWu2yvyFQj82bAarni/Rt17dcGkpCjjb8+71jaTLQjYiShkbY3 66VBLJgBgvwQ0QMLfeJHv1+0T0ZsXeH4Hkz/O1QiDsIujZVZEzD4Kr6RM832p5xWsYB9 N8Jw== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@veeam.com header.s=mx1-2022 header.b="cckSDW/Z"; 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 t1-20020a639541000000b0051b48085aaasi6755319pgn.858.2023.06.12.06.29.12; Mon, 12 Jun 2023 06:29:27 -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="cckSDW/Z"; 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 S236140AbjFLNXt (ORCPT + 99 others); Mon, 12 Jun 2023 09:23:49 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:53380 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229691AbjFLNXq (ORCPT ); Mon, 12 Jun 2023 09:23:46 -0400 Received: from mx1.veeam.com (mx1.veeam.com [216.253.77.21]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 89A7DAC; Mon, 12 Jun 2023 06:23:45 -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 9649E42462; Mon, 12 Jun 2023 09:23:42 -0400 (EDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=veeam.com; s=mx1-2022; t=1686576222; bh=ugxVl7Zf6JxnwJk4+LT20nHkkRjvyXw6j21wQSIhSbA=; h=From:To:CC:Subject:Date:In-Reply-To:References:From; b=cckSDW/Z0IIVrVH+rM+aMq5u+6xKx8iTSVCMoAfd4qbERhkVXy/haiQaCM/Rppoci HSbmkRc3cZ/UL3yKy8qgpE3HQsjsjrro4hmRqDpqikN+cMNGYsNiqj1NKbpl+MprWw Wkn/W6k/vkQn3h4Eg/aPjmR7QWo+pNbzuYfqxZ6DP9IsdPjmYWunzbkg8ghQWZTi1k 4qlfUP02430WjNxt479/H5HGFqyJWfRHTUvWLF8ECVC9xUvrqfKov86TugmeJ+qMW6 uhZ9LU6yItxmt4w+OQRI3yJPzb0StYG9lKeE6U2S538DpfRUxFOw+VTgbw2SB7AWlo VOLodivFt+mxQ== 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; Mon, 12 Jun 2023 15:23:39 +0200 From: Sergei Shtepa To: , , , CC: , , , , , , , , , , , , , Bagas Sanjaya Subject: [PATCH v5 01/11] documentation: Block Device Filtering Mechanism Date: Mon, 12 Jun 2023 15:21:27 +0200 Message-ID: <20230612132137.10362-2-sergei.shtepa@veeam.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20230612132137.10362-1-sergei.shtepa@veeam.com> References: <20230612132137.10362-1-sergei.shtepa@veeam.com> 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: 37303A29240315546D776B 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 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?1768503710503210569?= X-GMAIL-MSGID: =?utf-8?q?1768503710503210569?= 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 --- Documentation/block/blkfilter.rst | 64 +++++++++++++++++++++++++++++++ Documentation/block/index.rst | 1 + MAINTAINERS | 6 +++ 3 files changed, 71 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..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 e0ad886d3163..d801b8985b43 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -3580,6 +3580,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