On 2/3/21 7:53 AM, Sergei Shtepa wrote:
> remap_and_filter - describes the new features that
> blk_interposer provides for device mapper.
>
> Signed-off-by: Sergei Shtepa <sergei.shtepa@xxxxxxxxx>
Hi--
Please see comments below.
> ---
> .../admin-guide/device-mapper/index.rst | 1 +
> .../device-mapper/remap_and_filter.rst | 132 ++++++++++++++++++
> 2 files changed, 133 insertions(+)
> create mode 100644 Documentation/admin-guide/device-mapper/remap_and_filter.rst
> diff --git a/Documentation/admin-guide/device-mapper/remap_and_filter.rst b/Documentation/admin-guide/device-mapper/remap_and_filter.rst
> new file mode 100644
> index 000000000000..616b67998305
> --- /dev/null
> +++ b/Documentation/admin-guide/device-mapper/remap_and_filter.rst
> @@ -0,0 +1,132 @@
> +=================
> +DM remap & filter
> +=================
> +
> +Introduction
> +============
> +
> +Usually LVM should be used for new devices.
> +The administrator have to create logical volumes for the system partition
has
> +when installing the operating system. For a running system with
> +partitioned disk space and mounted file systems, it is quite difficult to
> +reconfigure to logical volumes. As a result, all the features that Device
> +Mapper provides are not available for non-LVM systems.
> +This problem is partially solved by the dm remap functionality, which
> +uses the kernel's blk_interposer.
> +
> +blk_interposer
> +==============
> +
> +Blk_interposer extends the capabilities of the DM, as it allows to
> +intercept and redirect bio requests for block devices that are not
> +dm device. At the same time, blk_interposer allows to attach and detach
devices.
> +from devices "on the fly", without stopping the execution of user
> +programs.
> +
> +Blk_interposer allows to do two tasks: remap and filter.
> +Remap allows to redirect all requests from one block device to another.
> +Filter allows to do additional processing of the request, but without
> +redirection. An intercepted request can get to the block device to which
> +it was addressed, without changes.
> +
> +Remap
> +=====
> +
> +Consider the functionality of the remap. This will allow to connect
> +any block device with a dm device "on the fly".
> +Suppose we have a file system mounted on the block device /dev/sda1::
> +
> + +-------------+
> + | file system |
> + +-------------+
> + ||
> + \/
> + +-------------+
> + | /dev/sda1 |
> + +-------------+
> +
> +Creating a new DM device that will be mapped on the same /dev/sda1::
Sometimes it's "DM", other times it's "dm" device. Please be consistent.
> +
> + +-------------+ +-----------+
> + | file system | | dm-linear |
> + +-------------+ +-----------+
> + || ||
> + \/ \/
> + +---------------+
> + | /dev/sda1 |
> + +---------------+
> +
> +Redirecting all bio requests for the /dev/sda1 device to the new dm
> +device::
> +
> + +-------------+
> + | file system |
> + +-------------+
> + ||
> + \/
> + +----------+ +-----------+
> + | remap | => | dm-linear |
> + +----------+ +-----------+
> + ||
> + \/
> + +-----------+
> + | /dev/sda1 |
> + +-----------+
> +
> +To achieve this, you need to:
> +
> +Create new dm device with option 'noexcl'. It's allow to open
allowed to open the
> +underlying block-device without the FMODE_EXCL flag::
> +
> + echo "0 `blockdev --getsz $1` linear $DEV 0 noexcl" | dmsetup create dm-noexcl
> +
> +Call remap command::
> +
> + dmsetup remap start dm-noexcl $1
> +
> +Remap can be used to extend the functionality of dm-snap. This will allow
> +to take snapshots from any block devices, not just logical volumes.
> +
> +Filter
> +======
> +
> +Filter does not redirect the bio to another device. It does not create
> +a clone of the bio request. After receiving the request, the filter can
> +only add some processing, complete the bio request, or return the bio
> +for further processing.
> +
> +Suppose we have a file system mounted on the block device /dev/sda1::
> +
> + +-------------+
> + | file system |
> + +-------------+
> + ||
> + \/
> + +-------------+
> + | /dev/sda1 |
> + +-------------+
> +
> +Creating a new dm device that will implement filter::
> +
> + +-------------+
> + | file system |
> + +-------------+
> + ||
> + \/
> + +--------+ +----------+
> + | filter | => | dm-delay |
> + +--------+ +----------+
> + ||
> + \/
> + +-------------+
> + | /dev/sda1 |
> + +-------------+
> +
> +Using filter we can change the behavior of debugging tools:
> + * dm-dust,
> + * dm-delay,
> + * dm-flakey,
> + * dm-verity.
> +
> +In the new version, they are will be able to change the behavior of any
Either they are able to change the behavior of any
or they will be able to change the behavior of any
I prefer the first choice.
> +existing block device, without creating a new one.
According to Documentation/doc-guide/sphinx.rst, here is how
chapters, sections, etc., should be indicated:
* Please stick to this order of heading adornments:
1. ``=`` with overline for document title::
==============
Document title
==============
2. ``=`` for chapters::
Chapters
========
3. ``-`` for sections::
Section
-------
4. ``~`` for subsections::
Subsection
~~~~~~~~~~
Although RST doesn't mandate a specific order ("Rather than imposing a fixed
number and order of section title adornment styles, the order enforced will be
the order as encountered."), having the higher levels the same overall makes
it easier to follow the documents.
thanks.
--
~Randy
