Hi--
On 6/9/23 04:58, Sergei Shtepa wrote:
> 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 <bagasdotme@xxxxxxxxx>
> Signed-off-by: Sergei Shtepa <sergei.shtepa@xxxxxxxxx>
> ---
> 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
that allows {what or who} to attach
so who/what does the attach? Is it a driver or a user or admin or something else?
and attach them to what?
> +device filters. Block device filters allow perform additional processing
allow performing ...
> +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
attach a filter
or
attach filters
> +changing the structure of block devices stack.
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,
> +filter can be managed using block device ioctl BLKFILTER_ATTACH,
a filter
or
the filter ioctls
> +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.
ioctls
> +It allows to attach a filter to a block device or detach it.
It allows a driver to attach a filter ...
?
> +
> +The ioctl BLKFILTER_CTL use structure blkfilter_ctl. It allows to send a
It allows a driver 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.
I'm having a problem with this "account" thingy. Can you explain more about it?
Is there an alternate word that might be used here?
> +
> +.. kernel-doc:: include/linux/blk-filter.h
> +
> +.. kernel-doc:: block/blk-filter.c
> + :export:
Thanks.
--
~Randy
