From patchwork Fri Nov 24 16:04:49 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sergei Shtepa X-Patchwork-Id: 169489 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a59:ce62:0:b0:403:3b70:6f57 with SMTP id o2csp1333976vqx; Fri, 24 Nov 2023 08:12:59 -0800 (PST) X-Google-Smtp-Source: AGHT+IHygptNkQAb1NrP7BYC0Bdh/LOKK7Ks/Uvx18pyoReM+HxFKrqtLdgYGkGk2MiEyYmE0m3+ X-Received: by 2002:a17:902:b281:b0:1cf:67e0:8904 with SMTP id u1-20020a170902b28100b001cf67e08904mr2533514plr.43.1700842378648; Fri, 24 Nov 2023 08:12:58 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1700842378; cv=none; d=google.com; s=arc-20160816; b=s4VffJ5vGq8SPF7upxAVn0kDFcIo/UD+VhmN4U/9aKaf3jb6UpHsj+D3LQ8rjhZ7va JD3+n/1NSWpAzXBI/PKraftt4vdyEO6BsdowbdoP4cTlfEekkOPsGYt8wLTuyT7PcDx4 4Z0HVX4ZPubBqM04V79xIrucUFKepX2WiwZp6m3QCnXbx1nsXGWVgsYrzGBxj8X159TM 9bNO24HG/DjZean27tokdKou0CNHyP41KmCau45UghDHBh2lYE8qHpmSj6iT0kVKJvQg FZbtK4rpAyv52dqP4GS9phk28R7s0GKmnP2v/q8CLwnkyUeXAFqR7v63cmqY/tuS3OHX xSgg== 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=sGVGOFmMLAnX+07bQNWtBjXylIzixACIEFOcvK9wZzw=; b=d82BuFkFP1u6wQnsKJES0l+U+FULF9Qa6bAW0KtDms8GUAUklrrBtEBkGRb8piJZ6d m7mmF/TlgodY8SlW745CvCDNhxGsQWwdNn/UJuIBpNBTj1p168298hCOQEi5bq/p8kKe meGIWwNlWL8LqX+48jVXEbI47ljkxr6CcefeU0ebS59SN6xYfnDMIg4tVAQJvk5ggO01 jMJUmGQC2dvcMIfGJyFYb75Ts6JVKPMUft9cgPk3ilYLtKWExg3aDo854IlVDrflV91W zUmoALNtxn0WnhyOECtMa4HG3qu5rNqCRAKS7Bn9SWsf+CFTKy4sYtZiKVmhQyCv2Lqt 0Isw== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linux.dev header.s=key1 header.b=i+W8szTl; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.37 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 snail.vger.email (snail.vger.email. [23.128.96.37]) by mx.google.com with ESMTPS id k17-20020a170902c41100b001cf6a75e986si3959776plk.456.2023.11.24.08.12.58 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 24 Nov 2023 08:12:58 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.37 as permitted sender) client-ip=23.128.96.37; Authentication-Results: mx.google.com; dkim=pass header.i=@linux.dev header.s=key1 header.b=i+W8szTl; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.37 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 snail.vger.email (Postfix) with ESMTP id 65633804DDA9; Fri, 24 Nov 2023 08:10:45 -0800 (PST) X-Virus-Status: Clean X-Virus-Scanned: clamav-milter 0.103.11 at snail.vger.email Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1345427AbjKXQKc (ORCPT + 99 others); Fri, 24 Nov 2023 11:10:32 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:41050 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S230104AbjKXQK2 (ORCPT ); Fri, 24 Nov 2023 11:10:28 -0500 X-Greylist: delayed 324 seconds by postgrey-1.37 at lindbergh.monkeyblade.net; Fri, 24 Nov 2023 08:10:32 PST Received: from out-173.mta0.migadu.com (out-173.mta0.migadu.com [IPv6:2001:41d0:1004:224b::ad]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id AD2DD19A6 for ; Fri, 24 Nov 2023 08:10:32 -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=1700841906; 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=i+W8szTlF1ZX//o0zn3QXAeuBOk3WNLnWrfX5T3uvLsnI36AB7e/JcQq1ZVfElXuFUCQXz qpCWKdhKVria4lWjdzd3wZ9V2f5GIGFYJH3nIjNlrv9obtGy0dGn2kphhkIOrUMcO7FLV5 mNDt4JzjkDsY9M8Yk0SE0GLdTzj/1WE= 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, dietmar.eggemann@arm.com, rostedt@goodmis.org, bsegall@google.com, mgorman@suse.de, bristot@redhat.com, vschneid@redhat.com, viro@zeniv.linux.org.uk, brauner@kernel.org, gregkh@linuxfoundation.org, arnd@arndb.de, christian.koenig@amd.com, yi.l.liu@intel.com, jirislaby@kernel.org, stfrench@microsoft.com, jpanis@baylibre.com, jgg@ziepe.ca, contact@emersion.fr, dchinner@redhat.com, jack@suse.cz, linux@weissschuh.net, min15.li@samsung.com, dlemoal@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:04:49 +0100 Message-Id: <20231124160459.26227-2-sergei.shtepa@linux.dev> In-Reply-To: <20231124160459.26227-1-sergei.shtepa@linux.dev> References: <20231124160459.26227-1-sergei.shtepa@linux.dev> MIME-Version: 1.0 X-Migadu-Flow: FLOW_OUT X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_BLOCKED, SPF_HELO_NONE,SPF_PASS,T_SCC_BODY_TEXT_LINE,URIBL_BLOCKED autolearn=unavailable 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-Greylist: Sender passed SPF test, not delayed by milter-greylist-4.6.4 (snail.vger.email [0.0.0.0]); Fri, 24 Nov 2023 08:10:45 -0800 (PST) X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1783462497627671561 X-GMAIL-MSGID: 1783462497627671561 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