that are not guaranteed to contain zeroes.
use_fec_from_device <fec_dev>
- Use forward error correction (FEC) to recover from corruption if hash
- verification fails. Use encoding data from the specified device. This
- may be the same device where data and hash blocks reside, in which case
- fec_start must be outside data and hash areas.
+ Use forward error correction (FEC) parity data from the specified device to
+ try to automatically recover from corruption and I/O errors.
- If the encoding data covers additional metadata, it must be accessible
- on the hash device after the hash blocks.
+ If this option is given, then <fec_roots> and <fec_blocks> must also be
+ given. <hash_block_size> must also be equal to <data_block_size>.
- Note: block sizes for data and hash devices must match. Also, if the
- verity <dev> is encrypted the <fec_dev> should be too.
+ <fec_dev> can be the same as <dev>, in which case <fec_start> must be
+ outside the data area. It can also be the same as <hash_dev>, in which case
+ <fec_start> must be outside the hash and optional additional metadata areas.
+
+ If the data <dev> is encrypted, the <fec_dev> should be too.
+
+ For more information, see `Forward error correction`_.
fec_roots <num>
- Number of generator roots. This equals to the number of parity bytes in
- the encoding data. For example, in RS(M, N) encoding, the number of roots
- is M-N.
+ The number of parity bytes in each 255-byte Reed-Solomon codeword. The
+ Reed-Solomon code used will be an RS(255, k) code where k = 255 - fec_roots.
+
+ The supported values are 2 through 24 inclusive. Higher values provide
+ stronger error correction. However, the minimum value of 2 already provides
+ strong error correction due to the use of interleaving, so 2 is the
+ recommended value for most users. fec_roots=2 corresponds to an
+ RS(255, 253) code, which has a space overhead of about 0.8%.
fec_blocks <num>
- The number of encoding data blocks on the FEC device. The block size for
- the FEC device is <data_block_size>.
+ The total number of <data_block_size> blocks that are error-checked using
+ FEC. This must be at least the sum of <num_data_blocks> and the number of
+ blocks needed by the hash tree. It can include additional metadata blocks,
+ which are assumed to be accessible on <hash_dev> following the hash blocks.
+
+ Note that this is *not* the number of parity blocks. The number of parity
+ blocks is inferred from <fec_blocks>, <fec_roots>, and <data_block_size>.
fec_start <offset>
- This is the offset, in <data_block_size> blocks, from the start of the
- FEC device to the beginning of the encoding data.
+ This is the offset, in <data_block_size> blocks, from the start of <fec_dev>
+ to the beginning of the parity data.
check_at_most_once
Verify data blocks only the first time they are read from the data device,
into the page cache. Block hashes are stored linearly, aligned to the nearest
block size.
-If forward error correction (FEC) support is enabled any recovery of
-corrupted data will be verified using the cryptographic hash of the
-corresponding data. This is why combining error correction with
-integrity checking is essential.
-
Hash Tree
---------
/ ... \ / . . . \ / \
blk_0 ... blk_127 blk_16256 blk_16383 blk_32640 . . . blk_32767
+Forward error correction
+------------------------
+
+dm-verity's optional forward error correction (FEC) support adds strong error
+correction capabilities to dm-verity. It allows systems that would be rendered
+inoperable by errors to continue operating, albeit with reduced performance.
+
+FEC uses Reed-Solomon (RS) codes that are interleaved across the entire
+device(s), allowing long bursts of corrupt or unreadable blocks to be recovered.
+
+dm-verity validates any FEC-corrected block against the wanted hash before using
+it. Therefore, FEC doesn't affect the security properties of dm-verity.
+
+The integration of FEC with dm-verity provides significant benefits over a
+separate error correction layer:
+
+- dm-verity invokes FEC only when a block's hash doesn't match the wanted hash
+ or the block cannot be read at all. As a result, FEC doesn't add overhead to
+ the common case where no error occurs.
+
+- dm-verity hashes are also used to identify erasure locations for RS decoding.
+ This allows correcting twice as many errors.
+
+FEC uses an RS(255, k) code where k = 255 - fec_roots. fec_roots is usually 2.
+This means that each k (usually 253) message bytes have fec_roots (usually 2)
+bytes of parity data added to get a 255-byte codeword. (Many external sources
+call RS codewords "blocks". Since dm-verity already uses the term "block" to
+mean something else, we'll use the clearer term "RS codeword".)
+
+FEC checks fec_blocks blocks of message data in total, consisting of:
+
+1. The data blocks from the data device
+2. The hash blocks from the hash device
+3. Optional additional metadata that follows the hash blocks on the hash device
+
+dm-verity assumes that the FEC parity data was computed as if the following
+procedure were followed:
+
+1. Concatenate the message data from the above sources.
+2. Zero-pad to the next multiple of k blocks. Let msg be the resulting byte
+ array, and msglen its length in bytes.
+3. For 0 <= i < msglen / k (for each RS codeword):
+ a. Select msg[i + j * msglen / k] for 0 <= j < k.
+ Consider these to be the 'k' message bytes of an RS codeword.
+ b. Compute the corresponding 'fec_roots' parity bytes of the RS codeword,
+ and concatenate them to the FEC parity data.
+
+Step 3a interleaves the RS codewords across the entire device using an
+interleaving degree of data_block_size * ceil(fec_blocks / k). This is the
+maximal interleaving, such that the message data consists of a region containing
+byte 0 of all the RS codewords, then a region containing byte 1 of all the RS
+codewords, and so on up to the region for byte 'k - 1'. Note that the number of
+codewords is set to a multiple of data_block_size; thus, the regions are
+block-aligned, and there is an implicit zero padding of up to 'k - 1' blocks.
+
+This interleaving allows long bursts of errors to be corrected. It provides
+much stronger error correction than storage devices typically provide, while
+keeping the space overhead low.
+
+The cost is slow decoding: correcting a single block usually requires reading
+254 extra blocks spread evenly across the device(s). However, that is
+acceptable because dm-verity uses FEC only when there is actually an error.
+
+The list below contains additional details about the RS codes used by
+dm-verity's FEC. Userspace programs that generate the parity data need to use
+these parameters for the parity data to match exactly:
+
+- Field used is GF(256)
+- Bytes are mapped to/from GF(256) elements in the natural way, where bits 0
+ through 7 (low-order to high-order) map to the coefficients of x^0 through x^7
+- Field generator polynomial is x^8 + x^4 + x^3 + x^2 + 1
+- The codes used are systematic, BCH-view codes
+- Primitive element alpha is 'x'
+- First consecutive root of code generator polynomial is 'x^0'
On-disk format
==============
projects / thirdparty / kernel / linux.git / commitdiff
