From patchwork Fri Nov 24 16:38:26 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sergei Shtepa X-Patchwork-Id: 169504 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a59:ce62:0:b0:403:3b70:6f57 with SMTP id o2csp1355280vqx; Fri, 24 Nov 2023 08:39:14 -0800 (PST) X-Google-Smtp-Source: AGHT+IF9wtIyhgdkp4SSfvMzexk4g9ECUOGhye2LSMOOGXCDOwS5C1QYL7IdRljUoOHemgT/sS/8 X-Received: by 2002:a05:6a20:c199:b0:188:24d0:e904 with SMTP id bg25-20020a056a20c19900b0018824d0e904mr4560792pzb.15.1700843953875; Fri, 24 Nov 2023 08:39:13 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1700843953; cv=none; d=google.com; s=arc-20160816; b=YsN6XAEGg3Opqew3sV8knLY2z6yWl9BEByfhWsUnQ0zsq9gqm8X/3zwo8iqqxI2lCN xw/GGTO5iGK3eCeUXKctrBvD/fOThavskcoJ3J+7vw2yyH69KWOht+h17XBinQVkTvdW IrbSslYpPLWr6VnmD8r0byY3oRsSd9FWKjEpiMBtyS6rWMaaDF74CGKnyfDlgsuZci0R oi7bs7e0SDYA5BrH9J5kv4q7Ao2nIzTnRIrFlorcNsFh4z4iKqoIbRoZGV6pTheI2hJQ e77kzJh2sKo7R1MNAqFFXCcmY54qOZvae74xKxpAMQvVZxK+OLuDWX4srplU5ZdS97vp 94XA== 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=NktJjNztL6a9VBLs/6z7OLOrm+oRflq1cbNxypOGnd4=; fh=a9ApmeGvcCB6Trsutt5tt4NXJ5Ik8LZp8ymXtojMIXc=; b=qnXEXsGWk65CNXH0xGc2GcNxZYwrnyi4BUY5z8ENaT2D2doCCmc6uTj0XVOtBFva4t DqtiJgiekqCxG5RjG/m76dIwwSM80+YMXQBjsg5GX3cfRfV+kZbbPxWsKob6oG3xpMO5 jWP6xq7Xcw+b7x6RoP7Idgu93zcKltsH7MSODydH4wwKtO4nCy0Fs9KbTAdlVMnOsLx8 oGeiiNC8BItgmbYfR13UPQN0wqrbu1Lgpr17pIjl+w0H+0WGKBC95khKI9CsgDDjqocn IfEnFsfMdzgpVyiyE9Diwp1aOcoudC32SF1E1Rqo6ye0pqAe4Ephx+KkdrWAhPc3FG0F xJrw== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linux.dev header.s=key1 header.b=SfNK5eG2; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.33 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linux.dev Received: from lipwig.vger.email (lipwig.vger.email. [23.128.96.33]) by mx.google.com with ESMTPS id ka40-20020a056a0093a800b006c4f047a75asi4004083pfb.225.2023.11.24.08.39.13 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 24 Nov 2023 08:39:13 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.33 as permitted sender) client-ip=23.128.96.33; Authentication-Results: mx.google.com; dkim=pass header.i=@linux.dev header.s=key1 header.b=SfNK5eG2; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.33 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linux.dev Received: from out1.vger.email (depot.vger.email [IPv6:2620:137:e000::3:0]) by lipwig.vger.email (Postfix) with ESMTP id A0A918250271; Fri, 24 Nov 2023 08:39:06 -0800 (PST) X-Virus-Status: Clean X-Virus-Scanned: clamav-milter 0.103.11 at lipwig.vger.email Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231213AbjKXQis (ORCPT + 99 others); Fri, 24 Nov 2023 11:38:48 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:51686 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231173AbjKXQiq (ORCPT ); Fri, 24 Nov 2023 11:38:46 -0500 Received: from out-186.mta0.migadu.com (out-186.mta0.migadu.com [91.218.175.186]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 52F95199A for ; Fri, 24 Nov 2023 08:38:51 -0800 (PST) X-Report-Abuse: Please report any abuse attempt to abuse@migadu.com and include these headers. DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linux.dev; s=key1; t=1700843929; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=NktJjNztL6a9VBLs/6z7OLOrm+oRflq1cbNxypOGnd4=; b=SfNK5eG2naW7wGMupnIWtWKUXuZAeJnaHN7zX9m/g28CcSS+kc7arWo7RETMFfBptJCBO0 PXyiAzQ7RbaOMdtVygtf3LDV5WmgOXWqYMEa2XSaWQZW62JYLkknW18DqWt7gBELiPC3OA dSn8uLrlj0UA9YAwmKmMv+Rj+r9qjFE= From: Sergei Shtepa To: axboe@kernel.dk, hch@infradead.org, corbet@lwn.net, snitzer@kernel.org Cc: mingo@redhat.com, peterz@infradead.org, juri.lelli@redhat.com, vincent.guittot@linaro.org, mgorman@suse.de, vschneid@redhat.com, viro@zeniv.linux.org.uk, brauner@kernel.org, linux-block@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, linux-fsdevel@vger.kernel.org, Sergei Shtepa Subject: [PATCH v6 01/11] documentation: Block Device Filtering Mechanism Date: Fri, 24 Nov 2023 17:38:26 +0100 Message-Id: <20231124163836.27256-2-sergei.shtepa@linux.dev> In-Reply-To: <20231124163836.27256-1-sergei.shtepa@linux.dev> References: <20231124163836.27256-1-sergei.shtepa@linux.dev> MIME-Version: 1.0 X-Migadu-Flow: FLOW_OUT X-Spam-Status: No, score=-0.9 required=5.0 tests=DKIM_SIGNED,DKIM_VALID, DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI, SPF_HELO_NONE,SPF_PASS,T_SCC_BODY_TEXT_LINE autolearn=unavailable autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lipwig.vger.email Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-Greylist: Sender passed SPF test, not delayed by milter-greylist-4.6.4 (lipwig.vger.email [0.0.0.0]); Fri, 24 Nov 2023 08:39:06 -0800 (PST) X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1783464149581839085 X-GMAIL-MSGID: 1783464149581839085 From: Sergei Shtepa 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 --- Documentation/block/blkfilter.rst | 66 +++++++++++++++++++++++++++++++ Documentation/block/index.rst | 1 + MAINTAINERS | 6 +++ 3 files changed, 73 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..4e148e78f3d4 --- /dev/null +++ b/Documentation/block/blkfilter.rst @@ -0,0 +1,66 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================ +Block Device Filtering Mechanism +================================ + +The block device filtering mechanism provides the ability to attach block +device filters. Block device filters allow performing 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 a filter to a block device "on the fly" without +changing the structure of the block device's 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, +the filter can be managed using block device ioctls 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 allows user-space programs to attach a block device +filter to a block device. The ioctl BLKFILTER_DETACH allows user-space programs +to detach it. Both ioctls use &struct blkfilter_name. The ioctl BLKFILTER_CTL +allows user-space programs to send a filter-specific command. It use &struct +blkfilter_ctl. + +.. kernel-doc:: include/uapi/linux/blk-filter.h + +To register in the system, the filter uses the &struct blkfilter_operations, +which contains callback functions, unique filter name and module owner. When +attaching a filter to a block device, the filter creates a &struct blkfilter. +The pointer to the &struct blkfilter allows the filter to determine for which +block device the callback functions are being called. + +.. 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 97f51d5ec1cf..c20cbec81b58 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -3584,6 +3584,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