[dm-devel] [PATCH] Improve the dm-integrity documentation.

[Russell Harmon]

Apologies for my inexperience here, but is this patch likely to get
included? I see there's been no discussion.

On Mon, May 29, 2023 at 5:20 PM Russell Harmon <eatnumber1 at gmail.com> wrote:
>
> Documents the meaning of the "buffer", adds documentation of the current
> defaults, and provides an example of how the tunables relate to each
> other.
>
> Signed-off-by: Russell Harmon <eatnumber1 at gmail.com>
> ---
>  .../device-mapper/dm-integrity.rst            | 44 ++++++++++++-------
>  1 file changed, 27 insertions(+), 17 deletions(-)
>
> diff --git a/Documentation/admin-guide/device-mapper/dm-integrity.rst b/Documentation/admin-guide/device-mapper/dm-integrity.rst
> index 8db172efa272..634a780d7c51 100644
> --- a/Documentation/admin-guide/device-mapper/dm-integrity.rst
> +++ b/Documentation/admin-guide/device-mapper/dm-integrity.rst
> @@ -25,7 +25,7 @@ mode it calculates and verifies the integrity tag internally. In this
>  mode, the dm-integrity target can be used to detect silent data
>  corruption on the disk or in the I/O path.
>
> -There's an alternate mode of operation where dm-integrity uses bitmap
> +There's an alternate mode of operation where dm-integrity uses a bitmap
>  instead of a journal. If a bit in the bitmap is 1, the corresponding
>  region's data and integrity tags are not synchronized - if the machine
>  crashes, the unsynchronized regions will be recalculated. The bitmap mode
> @@ -38,6 +38,15 @@ the device. But it will only format the device if the superblock contains
>  zeroes. If the superblock is neither valid nor zeroed, the dm-integrity
>  target can't be loaded.
>
> +Accesses to the on-disk metadata area containing checksums (aka tags) is
> +buffered using dm-bufio. When an access to any given metadata area
> +occurs, each unique metadata area gets its own buffer(s). The buffer size
> +is capped at the size of the metadata area, but may be smaller, thereby
> +requiring multiple buffers to represent the full metadata area. A smaller
> +buffer size will produce a smaller resulting read/write operation to the
> +metadata area for small reads/writes. A full write to the data covered by
> +a single buffer does *not* skip the read of the metadata.
> +
>  To use the target for the first time:
>
>  1. overwrite the superblock with zeroes
> @@ -93,7 +102,7 @@ journal_sectors:number
>         device. If the device is already formatted, the value from the
>         superblock is used.
>
> -interleave_sectors:number
> +interleave_sectors:number (default 32768)
>         The number of interleaved sectors. This values is rounded down to
>         a power of two. If the device is already formatted, the value from
>         the superblock is used.
> @@ -102,20 +111,16 @@ meta_device:device
>         Don't interleave the data and metadata on the device. Use a
>         separate device for metadata.
>
> -buffer_sectors:number
> -       The number of sectors in one buffer. The value is rounded down to
> -       a power of two.
> +buffer_sectors:number (default 128)
> +       The number of sectors in one metadata buffer. The value is rounded
> +       down to a power of two.
>
> -       The tag area is accessed using buffers, the buffer size is
> -       configurable. The large buffer size means that the I/O size will
> -       be larger, but there could be less I/Os issued.
> -
> -journal_watermark:number
> +journal_watermark:number (default 50)
>         The journal watermark in percents. When the size of the journal
>         exceeds this watermark, the thread that flushes the journal will
>         be started.
>
> -commit_time:number
> +commit_time:number (default 10000)
>         Commit time in milliseconds. When this time passes, the journal is
>         written. The journal is also written immediately if the FLUSH
>         request is received.
> @@ -163,11 +168,10 @@ journal_mac:algorithm(:key)       (the key is optional)
>         the journal. Thus, modified sector number would be detected at
>         this stage.
>
> -block_size:number
> -       The size of a data block in bytes.  The larger the block size the
> +block_size:number (default 512)
> +       The size of a data block in bytes. The larger the block size the
>         less overhead there is for per-block integrity metadata.
> -       Supported values are 512, 1024, 2048 and 4096 bytes.  If not
> -       specified the default block size is 512 bytes.
> +       Supported values are 512, 1024, 2048 and 4096 bytes.
>
>  sectors_per_bit:number
>         In the bitmap mode, this parameter specifies the number of
> @@ -209,6 +213,12 @@ table and swap the tables with suspend and resume). The other arguments
>  should not be changed when reloading the target because the layout of disk
>  data depend on them and the reloaded target would be non-functional.
>
> +For example, on a device using the default interleave_sectors of 32768, a
> +block_size of 512, and an internal_hash of crc32c with a tag size of 4
> +bytes, it will take 128 KiB of tags to track a full data area, requiring
> +256 sectors of metadata per data area. With the default buffer_sectors of
> +128, that means there will be 2 buffers per metadata area, or 2 buffers
> +per 16 MiB of data.
>
>  Status line:
>
> @@ -285,8 +295,8 @@ The layout of the formatted block device:
>  * one or more runs of interleaved tags and data.
>      Each run contains:
>
> -       * tag area - it contains integrity tags. There is one tag for each
> -         sector in the data area
> +       * tag area - it contains integrity tags. There is one tag for each sector in
> +         the data area. The size of this area is always 4KiB or greater.
>         * data area - it contains data sectors. The number of data sectors
>           in one run must be a power of two. log2 of this value is stored
>           in the superblock.
> --
> 2.34.1
>