0001 ==============
0002 Data Integrity
0003 ==============
0004
0005 1. Introduction
0006 ===============
0007
0008 Modern filesystems feature checksumming of data and metadata to
0009 protect against data corruption. However, the detection of the
0010 corruption is done at read time which could potentially be months
0011 after the data was written. At that point the original data that the
0012 application tried to write is most likely lost.
0013
0014 The solution is to ensure that the disk is actually storing what the
0015 application meant it to. Recent additions to both the SCSI family
0016 protocols (SBC Data Integrity Field, SCC protection proposal) as well
0017 as SATA/T13 (External Path Protection) try to remedy this by adding
0018 support for appending integrity metadata to an I/O. The integrity
0019 metadata (or protection information in SCSI terminology) includes a
0020 checksum for each sector as well as an incrementing counter that
0021 ensures the individual sectors are written in the right order. And
0022 for some protection schemes also that the I/O is written to the right
0023 place on disk.
0024
0025 Current storage controllers and devices implement various protective
0026 measures, for instance checksumming and scrubbing. But these
0027 technologies are working in their own isolated domains or at best
0028 between adjacent nodes in the I/O path. The interesting thing about
0029 DIF and the other integrity extensions is that the protection format
0030 is well defined and every node in the I/O path can verify the
0031 integrity of the I/O and reject it if corruption is detected. This
0032 allows not only corruption prevention but also isolation of the point
0033 of failure.
0034
0035 2. The Data Integrity Extensions
0036 ================================
0037
0038 As written, the protocol extensions only protect the path between
0039 controller and storage device. However, many controllers actually
0040 allow the operating system to interact with the integrity metadata
0041 (IMD). We have been working with several FC/SAS HBA vendors to enable
0042 the protection information to be transferred to and from their
0043 controllers.
0044
0045 The SCSI Data Integrity Field works by appending 8 bytes of protection
0046 information to each sector. The data + integrity metadata is stored
0047 in 520 byte sectors on disk. Data + IMD are interleaved when
0048 transferred between the controller and target. The T13 proposal is
0049 similar.
0050
0051 Because it is highly inconvenient for operating systems to deal with
0052 520 (and 4104) byte sectors, we approached several HBA vendors and
0053 encouraged them to allow separation of the data and integrity metadata
0054 scatter-gather lists.
0055
0056 The controller will interleave the buffers on write and split them on
0057 read. This means that Linux can DMA the data buffers to and from
0058 host memory without changes to the page cache.
0059
0060 Also, the 16-bit CRC checksum mandated by both the SCSI and SATA specs
0061 is somewhat heavy to compute in software. Benchmarks found that
0062 calculating this checksum had a significant impact on system
0063 performance for a number of workloads. Some controllers allow a
0064 lighter-weight checksum to be used when interfacing with the operating
0065 system. Emulex, for instance, supports the TCP/IP checksum instead.
0066 The IP checksum received from the OS is converted to the 16-bit CRC
0067 when writing and vice versa. This allows the integrity metadata to be
0068 generated by Linux or the application at very low cost (comparable to
0069 software RAID5).
0070
0071 The IP checksum is weaker than the CRC in terms of detecting bit
0072 errors. However, the strength is really in the separation of the data
0073 buffers and the integrity metadata. These two distinct buffers must
0074 match up for an I/O to complete.
0075
0076 The separation of the data and integrity metadata buffers as well as
0077 the choice in checksums is referred to as the Data Integrity
0078 Extensions. As these extensions are outside the scope of the protocol
0079 bodies (T10, T13), Oracle and its partners are trying to standardize
0080 them within the Storage Networking Industry Association.
0081
0082 3. Kernel Changes
0083 =================
0084
0085 The data integrity framework in Linux enables protection information
0086 to be pinned to I/Os and sent to/received from controllers that
0087 support it.
0088
0089 The advantage to the integrity extensions in SCSI and SATA is that
0090 they enable us to protect the entire path from application to storage
0091 device. However, at the same time this is also the biggest
0092 disadvantage. It means that the protection information must be in a
0093 format that can be understood by the disk.
0094
0095 Generally Linux/POSIX applications are agnostic to the intricacies of
0096 the storage devices they are accessing. The virtual filesystem switch
0097 and the block layer make things like hardware sector size and
0098 transport protocols completely transparent to the application.
0099
0100 However, this level of detail is required when preparing the
0101 protection information to send to a disk. Consequently, the very
0102 concept of an end-to-end protection scheme is a layering violation.
0103 It is completely unreasonable for an application to be aware whether
0104 it is accessing a SCSI or SATA disk.
0105
0106 The data integrity support implemented in Linux attempts to hide this
0107 from the application. As far as the application (and to some extent
0108 the kernel) is concerned, the integrity metadata is opaque information
0109 that's attached to the I/O.
0110
0111 The current implementation allows the block layer to automatically
0112 generate the protection information for any I/O. Eventually the
0113 intent is to move the integrity metadata calculation to userspace for
0114 user data. Metadata and other I/O that originates within the kernel
0115 will still use the automatic generation interface.
0116
0117 Some storage devices allow each hardware sector to be tagged with a
0118 16-bit value. The owner of this tag space is the owner of the block
0119 device. I.e. the filesystem in most cases. The filesystem can use
0120 this extra space to tag sectors as they see fit. Because the tag
0121 space is limited, the block interface allows tagging bigger chunks by
0122 way of interleaving. This way, 8*16 bits of information can be
0123 attached to a typical 4KB filesystem block.
0124
0125 This also means that applications such as fsck and mkfs will need
0126 access to manipulate the tags from user space. A passthrough
0127 interface for this is being worked on.
0128
0129
0130 4. Block Layer Implementation Details
0131 =====================================
0132
0133 4.1 Bio
0134 -------
0135
0136 The data integrity patches add a new field to struct bio when
0137 CONFIG_BLK_DEV_INTEGRITY is enabled. bio_integrity(bio) returns a
0138 pointer to a struct bip which contains the bio integrity payload.
0139 Essentially a bip is a trimmed down struct bio which holds a bio_vec
0140 containing the integrity metadata and the required housekeeping
0141 information (bvec pool, vector count, etc.)
0142
0143 A kernel subsystem can enable data integrity protection on a bio by
0144 calling bio_integrity_alloc(bio). This will allocate and attach the
0145 bip to the bio.
0146
0147 Individual pages containing integrity metadata can subsequently be
0148 attached using bio_integrity_add_page().
0149
0150 bio_free() will automatically free the bip.
0151
0152
0153 4.2 Block Device
0154 ----------------
0155
0156 Because the format of the protection data is tied to the physical
0157 disk, each block device has been extended with a block integrity
0158 profile (struct blk_integrity). This optional profile is registered
0159 with the block layer using blk_integrity_register().
0160
0161 The profile contains callback functions for generating and verifying
0162 the protection data, as well as getting and setting application tags.
0163 The profile also contains a few constants to aid in completing,
0164 merging and splitting the integrity metadata.
0165
0166 Layered block devices will need to pick a profile that's appropriate
0167 for all subdevices. blk_integrity_compare() can help with that. DM
0168 and MD linear, RAID0 and RAID1 are currently supported. RAID4/5/6
0169 will require extra work due to the application tag.
0170
0171
0172 5.0 Block Layer Integrity API
0173 =============================
0174
0175 5.1 Normal Filesystem
0176 ---------------------
0177
0178 The normal filesystem is unaware that the underlying block device
0179 is capable of sending/receiving integrity metadata. The IMD will
0180 be automatically generated by the block layer at submit_bio() time
0181 in case of a WRITE. A READ request will cause the I/O integrity
0182 to be verified upon completion.
0183
0184 IMD generation and verification can be toggled using the::
0185
0186 /sys/block/<bdev>/integrity/write_generate
0187
0188 and::
0189
0190 /sys/block/<bdev>/integrity/read_verify
0191
0192 flags.
0193
0194
0195 5.2 Integrity-Aware Filesystem
0196 ------------------------------
0197
0198 A filesystem that is integrity-aware can prepare I/Os with IMD
0199 attached. It can also use the application tag space if this is
0200 supported by the block device.
0201
0202
0203 `bool bio_integrity_prep(bio);`
0204
0205 To generate IMD for WRITE and to set up buffers for READ, the
0206 filesystem must call bio_integrity_prep(bio).
0207
0208 Prior to calling this function, the bio data direction and start
0209 sector must be set, and the bio should have all data pages
0210 added. It is up to the caller to ensure that the bio does not
0211 change while I/O is in progress.
0212 Complete bio with error if prepare failed for some reson.
0213
0214
0215 5.3 Passing Existing Integrity Metadata
0216 ---------------------------------------
0217
0218 Filesystems that either generate their own integrity metadata or
0219 are capable of transferring IMD from user space can use the
0220 following calls:
0221
0222
0223 `struct bip * bio_integrity_alloc(bio, gfp_mask, nr_pages);`
0224
0225 Allocates the bio integrity payload and hangs it off of the bio.
0226 nr_pages indicate how many pages of protection data need to be
0227 stored in the integrity bio_vec list (similar to bio_alloc()).
0228
0229 The integrity payload will be freed at bio_free() time.
0230
0231
0232 `int bio_integrity_add_page(bio, page, len, offset);`
0233
0234 Attaches a page containing integrity metadata to an existing
0235 bio. The bio must have an existing bip,
0236 i.e. bio_integrity_alloc() must have been called. For a WRITE,
0237 the integrity metadata in the pages must be in a format
0238 understood by the target device with the notable exception that
0239 the sector numbers will be remapped as the request traverses the
0240 I/O stack. This implies that the pages added using this call
0241 will be modified during I/O! The first reference tag in the
0242 integrity metadata must have a value of bip->bip_sector.
0243
0244 Pages can be added using bio_integrity_add_page() as long as
0245 there is room in the bip bio_vec array (nr_pages).
0246
0247 Upon completion of a READ operation, the attached pages will
0248 contain the integrity metadata received from the storage device.
0249 It is up to the receiver to process them and verify data
0250 integrity upon completion.
0251
0252
0253 5.4 Registering A Block Device As Capable Of Exchanging Integrity Metadata
0254 --------------------------------------------------------------------------
0255
0256 To enable integrity exchange on a block device the gendisk must be
0257 registered as capable:
0258
0259 `int blk_integrity_register(gendisk, blk_integrity);`
0260
0261 The blk_integrity struct is a template and should contain the
0262 following::
0263
0264 static struct blk_integrity my_profile = {
0265 .name = "STANDARDSBODY-TYPE-VARIANT-CSUM",
0266 .generate_fn = my_generate_fn,
0267 .verify_fn = my_verify_fn,
0268 .tuple_size = sizeof(struct my_tuple_size),
0269 .tag_size = <tag bytes per hw sector>,
0270 };
0271
0272 'name' is a text string which will be visible in sysfs. This is
0273 part of the userland API so chose it carefully and never change
0274 it. The format is standards body-type-variant.
0275 E.g. T10-DIF-TYPE1-IP or T13-EPP-0-CRC.
0276
0277 'generate_fn' generates appropriate integrity metadata (for WRITE).
0278
0279 'verify_fn' verifies that the data buffer matches the integrity
0280 metadata.
0281
0282 'tuple_size' must be set to match the size of the integrity
0283 metadata per sector. I.e. 8 for DIF and EPP.
0284
0285 'tag_size' must be set to identify how many bytes of tag space
0286 are available per hardware sector. For DIF this is either 2 or
0287 0 depending on the value of the Control Mode Page ATO bit.
0288
0289 ----------------------------------------------------------------------
0290
0291 2007-12-24 Martin K. Petersen <martin.petersen@oracle.com>
