From 4c2c845bdc9a3443ce805460a75242923b0c5ab5 Mon Sep 17 00:00:00 2001 From: Mikulas Patocka Date: Mon, 1 May 2023 09:20:08 -0400 Subject: dm flakey: introduce random_read_corrupt and random_write_corrupt options The random_read_corrupt and random_write_corrupt options corrupt a random byte in a bio with the provided probability. The corruption only happens in the "down" interval. Signed-off-by: Mikulas Patocka Signed-off-by: Mike Snitzer --- Documentation/admin-guide/device-mapper/dm-flakey.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'Documentation/admin-guide') diff --git a/Documentation/admin-guide/device-mapper/dm-flakey.rst b/Documentation/admin-guide/device-mapper/dm-flakey.rst index f7104c01b0f7..f967c5fea219 100644 --- a/Documentation/admin-guide/device-mapper/dm-flakey.rst +++ b/Documentation/admin-guide/device-mapper/dm-flakey.rst @@ -67,6 +67,16 @@ Optional feature parameters: Perform the replacement only if bio->bi_opf has all the selected flags set. + random_read_corrupt + During , replace random byte in a read bio + with a random value. probability is an integer between + 0 and 1000000000 meaning 0% to 100% probability of corruption. + + random_write_corrupt + During , replace random byte in a write bio + with a random value. probability is an integer between + 0 and 1000000000 meaning 0% to 100% probability of corruption. + Examples: Replaces the 32nd byte of READ bios with the value 1:: -- cgit v1.2.3 From c3ba5aa6f789097364398ad38fe541841bade17d Mon Sep 17 00:00:00 2001 From: Russell Harmon Date: Sun, 4 Jun 2023 22:08:50 -0700 Subject: Documentation: dm-integrity: Fix minor grammatical error. "where dm-integrity uses bitmap" becomes "where dm-integrity uses a bitmap" Signed-off-by: Russell Harmon Reviewed-by: Bagas Sanjaya Signed-off-by: Mike Snitzer --- Documentation/admin-guide/device-mapper/dm-integrity.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/admin-guide') diff --git a/Documentation/admin-guide/device-mapper/dm-integrity.rst b/Documentation/admin-guide/device-mapper/dm-integrity.rst index 8db172efa272..b2a698e955a3 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 -- cgit v1.2.3 From 3b671459e687e6b7d3f87d39a0b242bbebf871be Mon Sep 17 00:00:00 2001 From: Russell Harmon Date: Sun, 4 Jun 2023 22:08:51 -0700 Subject: Documentation: dm-integrity: Document the meaning of "buffer". "Buffers" are buffers of the metadata/checksum area of dm-integrity. They are always at most as large as a single metadata area on-disk, but may be smaller. Signed-off-by: Russell Harmon Reviewed-by: Bagas Sanjaya Signed-off-by: Mike Snitzer --- Documentation/admin-guide/device-mapper/dm-integrity.rst | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) (limited to 'Documentation/admin-guide') diff --git a/Documentation/admin-guide/device-mapper/dm-integrity.rst b/Documentation/admin-guide/device-mapper/dm-integrity.rst index b2a698e955a3..31f514675809 100644 --- a/Documentation/admin-guide/device-mapper/dm-integrity.rst +++ b/Documentation/admin-guide/device-mapper/dm-integrity.rst @@ -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) are +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. The metadata is still read even in +a full write to the data covered by a single buffer. + To use the target for the first time: 1. overwrite the superblock with zeroes @@ -106,10 +115,6 @@ buffer_sectors:number The number of sectors in one 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 The journal watermark in percents. When the size of the journal exceeds this watermark, the thread that flushes the journal will -- cgit v1.2.3 From 52145f284c66b9de5be7b054444dd0da066079d6 Mon Sep 17 00:00:00 2001 From: Russell Harmon Date: Sun, 4 Jun 2023 22:08:52 -0700 Subject: Documentation: dm-integrity: Document default values. Signed-off-by: Russell Harmon Signed-off-by: Mike Snitzer --- .../admin-guide/device-mapper/dm-integrity.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) (limited to 'Documentation/admin-guide') diff --git a/Documentation/admin-guide/device-mapper/dm-integrity.rst b/Documentation/admin-guide/device-mapper/dm-integrity.rst index 31f514675809..0241457c0027 100644 --- a/Documentation/admin-guide/device-mapper/dm-integrity.rst +++ b/Documentation/admin-guide/device-mapper/dm-integrity.rst @@ -102,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. @@ -111,16 +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. -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. @@ -168,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 @@ -291,7 +290,8 @@ The layout of the formatted block device: Each run contains: * tag area - it contains integrity tags. There is one tag for each - sector in the data area + 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. -- cgit v1.2.3 From 2971c058746319e9853919553259cef7fe280c94 Mon Sep 17 00:00:00 2001 From: Russell Harmon Date: Sun, 4 Jun 2023 22:08:53 -0700 Subject: Documentation: dm-integrity: Document an example of how the tunables relate. Signed-off-by: Russell Harmon Signed-off-by: Mike Snitzer --- Documentation/admin-guide/device-mapper/dm-integrity.rst | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'Documentation/admin-guide') diff --git a/Documentation/admin-guide/device-mapper/dm-integrity.rst b/Documentation/admin-guide/device-mapper/dm-integrity.rst index 0241457c0027..d8a5f14d0e3c 100644 --- a/Documentation/admin-guide/device-mapper/dm-integrity.rst +++ b/Documentation/admin-guide/device-mapper/dm-integrity.rst @@ -213,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: -- cgit v1.2.3