1 ============== 1 ==============
2 Data Integrity 2 Data Integrity
3 ============== 3 ==============
4 4
5 1. Introduction 5 1. Introduction
6 =============== 6 ===============
7 7
8 Modern filesystems feature checksumming of dat 8 Modern filesystems feature checksumming of data and metadata to
9 protect against data corruption. However, the 9 protect against data corruption. However, the detection of the
10 corruption is done at read time which could po 10 corruption is done at read time which could potentially be months
11 after the data was written. At that point the 11 after the data was written. At that point the original data that the
12 application tried to write is most likely lost 12 application tried to write is most likely lost.
13 13
14 The solution is to ensure that the disk is act 14 The solution is to ensure that the disk is actually storing what the
15 application meant it to. Recent additions to 15 application meant it to. Recent additions to both the SCSI family
16 protocols (SBC Data Integrity Field, SCC prote 16 protocols (SBC Data Integrity Field, SCC protection proposal) as well
17 as SATA/T13 (External Path Protection) try to 17 as SATA/T13 (External Path Protection) try to remedy this by adding
18 support for appending integrity metadata to an 18 support for appending integrity metadata to an I/O. The integrity
19 metadata (or protection information in SCSI te 19 metadata (or protection information in SCSI terminology) includes a
20 checksum for each sector as well as an increme 20 checksum for each sector as well as an incrementing counter that
21 ensures the individual sectors are written in 21 ensures the individual sectors are written in the right order. And
22 for some protection schemes also that the I/O 22 for some protection schemes also that the I/O is written to the right
23 place on disk. 23 place on disk.
24 24
25 Current storage controllers and devices implem 25 Current storage controllers and devices implement various protective
26 measures, for instance checksumming and scrubb 26 measures, for instance checksumming and scrubbing. But these
27 technologies are working in their own isolated 27 technologies are working in their own isolated domains or at best
28 between adjacent nodes in the I/O path. The i 28 between adjacent nodes in the I/O path. The interesting thing about
29 DIF and the other integrity extensions is that 29 DIF and the other integrity extensions is that the protection format
30 is well defined and every node in the I/O path 30 is well defined and every node in the I/O path can verify the
31 integrity of the I/O and reject it if corrupti 31 integrity of the I/O and reject it if corruption is detected. This
32 allows not only corruption prevention but also 32 allows not only corruption prevention but also isolation of the point
33 of failure. 33 of failure.
34 34
35 2. The Data Integrity Extensions 35 2. The Data Integrity Extensions
36 ================================ 36 ================================
37 37
38 As written, the protocol extensions only prote 38 As written, the protocol extensions only protect the path between
39 controller and storage device. However, many 39 controller and storage device. However, many controllers actually
40 allow the operating system to interact with th 40 allow the operating system to interact with the integrity metadata
41 (IMD). We have been working with several FC/S 41 (IMD). We have been working with several FC/SAS HBA vendors to enable
42 the protection information to be transferred t 42 the protection information to be transferred to and from their
43 controllers. 43 controllers.
44 44
45 The SCSI Data Integrity Field works by appendi 45 The SCSI Data Integrity Field works by appending 8 bytes of protection
46 information to each sector. The data + integr 46 information to each sector. The data + integrity metadata is stored
47 in 520 byte sectors on disk. Data + IMD are i 47 in 520 byte sectors on disk. Data + IMD are interleaved when
48 transferred between the controller and target. 48 transferred between the controller and target. The T13 proposal is
49 similar. 49 similar.
50 50
51 Because it is highly inconvenient for operatin 51 Because it is highly inconvenient for operating systems to deal with
52 520 (and 4104) byte sectors, we approached sev 52 520 (and 4104) byte sectors, we approached several HBA vendors and
53 encouraged them to allow separation of the dat 53 encouraged them to allow separation of the data and integrity metadata
54 scatter-gather lists. 54 scatter-gather lists.
55 55
56 The controller will interleave the buffers on 56 The controller will interleave the buffers on write and split them on
57 read. This means that Linux can DMA the data 57 read. This means that Linux can DMA the data buffers to and from
58 host memory without changes to the page cache. 58 host memory without changes to the page cache.
59 59
60 Also, the 16-bit CRC checksum mandated by both 60 Also, the 16-bit CRC checksum mandated by both the SCSI and SATA specs
61 is somewhat heavy to compute in software. Ben 61 is somewhat heavy to compute in software. Benchmarks found that
62 calculating this checksum had a significant im 62 calculating this checksum had a significant impact on system
63 performance for a number of workloads. Some c 63 performance for a number of workloads. Some controllers allow a
64 lighter-weight checksum to be used when interf 64 lighter-weight checksum to be used when interfacing with the operating
65 system. Emulex, for instance, supports the TC 65 system. Emulex, for instance, supports the TCP/IP checksum instead.
66 The IP checksum received from the OS is conver 66 The IP checksum received from the OS is converted to the 16-bit CRC
67 when writing and vice versa. This allows the 67 when writing and vice versa. This allows the integrity metadata to be
68 generated by Linux or the application at very 68 generated by Linux or the application at very low cost (comparable to
69 software RAID5). 69 software RAID5).
70 70
71 The IP checksum is weaker than the CRC in term 71 The IP checksum is weaker than the CRC in terms of detecting bit
72 errors. However, the strength is really in th 72 errors. However, the strength is really in the separation of the data
73 buffers and the integrity metadata. These two 73 buffers and the integrity metadata. These two distinct buffers must
74 match up for an I/O to complete. 74 match up for an I/O to complete.
75 75
76 The separation of the data and integrity metad 76 The separation of the data and integrity metadata buffers as well as
77 the choice in checksums is referred to as the 77 the choice in checksums is referred to as the Data Integrity
78 Extensions. As these extensions are outside t 78 Extensions. As these extensions are outside the scope of the protocol
79 bodies (T10, T13), Oracle and its partners are 79 bodies (T10, T13), Oracle and its partners are trying to standardize
80 them within the Storage Networking Industry As 80 them within the Storage Networking Industry Association.
81 81
82 3. Kernel Changes 82 3. Kernel Changes
83 ================= 83 =================
84 84
85 The data integrity framework in Linux enables 85 The data integrity framework in Linux enables protection information
86 to be pinned to I/Os and sent to/received from 86 to be pinned to I/Os and sent to/received from controllers that
87 support it. 87 support it.
88 88
89 The advantage to the integrity extensions in S 89 The advantage to the integrity extensions in SCSI and SATA is that
90 they enable us to protect the entire path from 90 they enable us to protect the entire path from application to storage
91 device. However, at the same time this is als 91 device. However, at the same time this is also the biggest
92 disadvantage. It means that the protection inf 92 disadvantage. It means that the protection information must be in a
93 format that can be understood by the disk. 93 format that can be understood by the disk.
94 94
95 Generally Linux/POSIX applications are agnosti 95 Generally Linux/POSIX applications are agnostic to the intricacies of
96 the storage devices they are accessing. The v 96 the storage devices they are accessing. The virtual filesystem switch
97 and the block layer make things like hardware 97 and the block layer make things like hardware sector size and
98 transport protocols completely transparent to 98 transport protocols completely transparent to the application.
99 99
100 However, this level of detail is required when 100 However, this level of detail is required when preparing the
101 protection information to send to a disk. Con 101 protection information to send to a disk. Consequently, the very
102 concept of an end-to-end protection scheme is 102 concept of an end-to-end protection scheme is a layering violation.
103 It is completely unreasonable for an applicati 103 It is completely unreasonable for an application to be aware whether
104 it is accessing a SCSI or SATA disk. 104 it is accessing a SCSI or SATA disk.
105 105
106 The data integrity support implemented in Linu 106 The data integrity support implemented in Linux attempts to hide this
107 from the application. As far as the applicati 107 from the application. As far as the application (and to some extent
108 the kernel) is concerned, the integrity metada 108 the kernel) is concerned, the integrity metadata is opaque information
109 that's attached to the I/O. 109 that's attached to the I/O.
110 110
111 The current implementation allows the block la 111 The current implementation allows the block layer to automatically
112 generate the protection information for any I/ 112 generate the protection information for any I/O. Eventually the
113 intent is to move the integrity metadata calcu 113 intent is to move the integrity metadata calculation to userspace for
114 user data. Metadata and other I/O that origin 114 user data. Metadata and other I/O that originates within the kernel
115 will still use the automatic generation interf 115 will still use the automatic generation interface.
116 116
117 Some storage devices allow each hardware secto 117 Some storage devices allow each hardware sector to be tagged with a
118 16-bit value. The owner of this tag space is 118 16-bit value. The owner of this tag space is the owner of the block
119 device. I.e. the filesystem in most cases. T 119 device. I.e. the filesystem in most cases. The filesystem can use
120 this extra space to tag sectors as they see fi 120 this extra space to tag sectors as they see fit. Because the tag
121 space is limited, the block interface allows t 121 space is limited, the block interface allows tagging bigger chunks by
122 way of interleaving. This way, 8*16 bits of i 122 way of interleaving. This way, 8*16 bits of information can be
123 attached to a typical 4KB filesystem block. 123 attached to a typical 4KB filesystem block.
124 124
125 This also means that applications such as fsck 125 This also means that applications such as fsck and mkfs will need
126 access to manipulate the tags from user space. 126 access to manipulate the tags from user space. A passthrough
127 interface for this is being worked on. 127 interface for this is being worked on.
128 128
129 129
130 4. Block Layer Implementation Details 130 4. Block Layer Implementation Details
131 ===================================== 131 =====================================
132 132
133 4.1 Bio 133 4.1 Bio
134 ------- 134 -------
135 135
136 The data integrity patches add a new field to 136 The data integrity patches add a new field to struct bio when
137 CONFIG_BLK_DEV_INTEGRITY is enabled. bio_inte 137 CONFIG_BLK_DEV_INTEGRITY is enabled. bio_integrity(bio) returns a
138 pointer to a struct bip which contains the bio 138 pointer to a struct bip which contains the bio integrity payload.
139 Essentially a bip is a trimmed down struct bio 139 Essentially a bip is a trimmed down struct bio which holds a bio_vec
140 containing the integrity metadata and the requ 140 containing the integrity metadata and the required housekeeping
141 information (bvec pool, vector count, etc.) 141 information (bvec pool, vector count, etc.)
142 142
143 A kernel subsystem can enable data integrity p 143 A kernel subsystem can enable data integrity protection on a bio by
144 calling bio_integrity_alloc(bio). This will a 144 calling bio_integrity_alloc(bio). This will allocate and attach the
145 bip to the bio. 145 bip to the bio.
146 146
147 Individual pages containing integrity metadata 147 Individual pages containing integrity metadata can subsequently be
148 attached using bio_integrity_add_page(). 148 attached using bio_integrity_add_page().
149 149
150 bio_free() will automatically free the bip. 150 bio_free() will automatically free the bip.
151 151
152 152
153 4.2 Block Device 153 4.2 Block Device
154 ---------------- 154 ----------------
155 155
156 Block devices can set up the integrity informa !! 156 Because the format of the protection data is tied to the physical
157 sub-struture of the queue_limits structure. !! 157 disk, each block device has been extended with a block integrity
>> 158 profile (struct blk_integrity). This optional profile is registered
>> 159 with the block layer using blk_integrity_register().
>> 160
>> 161 The profile contains callback functions for generating and verifying
>> 162 the protection data, as well as getting and setting application tags.
>> 163 The profile also contains a few constants to aid in completing,
>> 164 merging and splitting the integrity metadata.
158 165
159 Layered block devices will need to pick a prof 166 Layered block devices will need to pick a profile that's appropriate
160 for all subdevices. queue_limits_stack_integr !! 167 for all subdevices. blk_integrity_compare() can help with that. DM
161 and MD linear, RAID0 and RAID1 are currently s 168 and MD linear, RAID0 and RAID1 are currently supported. RAID4/5/6
162 will require extra work due to the application 169 will require extra work due to the application tag.
163 170
164 171
165 5.0 Block Layer Integrity API 172 5.0 Block Layer Integrity API
166 ============================= 173 =============================
167 174
168 5.1 Normal Filesystem 175 5.1 Normal Filesystem
169 --------------------- 176 ---------------------
170 177
171 The normal filesystem is unaware that the 178 The normal filesystem is unaware that the underlying block device
172 is capable of sending/receiving integrity 179 is capable of sending/receiving integrity metadata. The IMD will
173 be automatically generated by the block la 180 be automatically generated by the block layer at submit_bio() time
174 in case of a WRITE. A READ request will c 181 in case of a WRITE. A READ request will cause the I/O integrity
175 to be verified upon completion. 182 to be verified upon completion.
176 183
177 IMD generation and verification can be tog 184 IMD generation and verification can be toggled using the::
178 185
179 /sys/block/<bdev>/integrity/write_genera 186 /sys/block/<bdev>/integrity/write_generate
180 187
181 and:: 188 and::
182 189
183 /sys/block/<bdev>/integrity/read_verify 190 /sys/block/<bdev>/integrity/read_verify
184 191
185 flags. 192 flags.
186 193
187 194
188 5.2 Integrity-Aware Filesystem 195 5.2 Integrity-Aware Filesystem
189 ------------------------------ 196 ------------------------------
190 197
191 A filesystem that is integrity-aware can p 198 A filesystem that is integrity-aware can prepare I/Os with IMD
192 attached. It can also use the application 199 attached. It can also use the application tag space if this is
193 supported by the block device. 200 supported by the block device.
194 201
195 202
196 `bool bio_integrity_prep(bio);` 203 `bool bio_integrity_prep(bio);`
197 204
198 To generate IMD for WRITE and to set up 205 To generate IMD for WRITE and to set up buffers for READ, the
199 filesystem must call bio_integrity_prep( 206 filesystem must call bio_integrity_prep(bio).
200 207
201 Prior to calling this function, the bio 208 Prior to calling this function, the bio data direction and start
202 sector must be set, and the bio should h 209 sector must be set, and the bio should have all data pages
203 added. It is up to the caller to ensure 210 added. It is up to the caller to ensure that the bio does not
204 change while I/O is in progress. 211 change while I/O is in progress.
205 Complete bio with error if prepare faile 212 Complete bio with error if prepare failed for some reason.
206 213
207 214
208 5.3 Passing Existing Integrity Metadata 215 5.3 Passing Existing Integrity Metadata
209 --------------------------------------- 216 ---------------------------------------
210 217
211 Filesystems that either generate their own 218 Filesystems that either generate their own integrity metadata or
212 are capable of transferring IMD from user 219 are capable of transferring IMD from user space can use the
213 following calls: 220 following calls:
214 221
215 222
216 `struct bip * bio_integrity_alloc(bio, gfp 223 `struct bip * bio_integrity_alloc(bio, gfp_mask, nr_pages);`
217 224
218 Allocates the bio integrity payload and 225 Allocates the bio integrity payload and hangs it off of the bio.
219 nr_pages indicate how many pages of prot 226 nr_pages indicate how many pages of protection data need to be
220 stored in the integrity bio_vec list (si 227 stored in the integrity bio_vec list (similar to bio_alloc()).
221 228
222 The integrity payload will be freed at b 229 The integrity payload will be freed at bio_free() time.
223 230
224 231
225 `int bio_integrity_add_page(bio, page, len 232 `int bio_integrity_add_page(bio, page, len, offset);`
226 233
227 Attaches a page containing integrity met 234 Attaches a page containing integrity metadata to an existing
228 bio. The bio must have an existing bip, 235 bio. The bio must have an existing bip,
229 i.e. bio_integrity_alloc() must have bee 236 i.e. bio_integrity_alloc() must have been called. For a WRITE,
230 the integrity metadata in the pages must 237 the integrity metadata in the pages must be in a format
231 understood by the target device with the 238 understood by the target device with the notable exception that
232 the sector numbers will be remapped as t 239 the sector numbers will be remapped as the request traverses the
233 I/O stack. This implies that the pages 240 I/O stack. This implies that the pages added using this call
234 will be modified during I/O! The first 241 will be modified during I/O! The first reference tag in the
235 integrity metadata must have a value of 242 integrity metadata must have a value of bip->bip_sector.
236 243
237 Pages can be added using bio_integrity_a 244 Pages can be added using bio_integrity_add_page() as long as
238 there is room in the bip bio_vec array ( 245 there is room in the bip bio_vec array (nr_pages).
239 246
240 Upon completion of a READ operation, the 247 Upon completion of a READ operation, the attached pages will
241 contain the integrity metadata received 248 contain the integrity metadata received from the storage device.
242 It is up to the receiver to process them 249 It is up to the receiver to process them and verify data
243 integrity upon completion. 250 integrity upon completion.
244 251
>> 252
>> 253 5.4 Registering A Block Device As Capable Of Exchanging Integrity Metadata
>> 254 --------------------------------------------------------------------------
>> 255
>> 256 To enable integrity exchange on a block device the gendisk must be
>> 257 registered as capable:
>> 258
>> 259 `int blk_integrity_register(gendisk, blk_integrity);`
>> 260
>> 261 The blk_integrity struct is a template and should contain the
>> 262 following::
>> 263
>> 264 static struct blk_integrity my_profile = {
>> 265 .name = "STANDARDSBODY-TYPE-VARIANT-CSUM",
>> 266 .generate_fn = my_generate_fn,
>> 267 .verify_fn = my_verify_fn,
>> 268 .tuple_size = sizeof(struct my_tuple_size),
>> 269 .tag_size = <tag bytes per hw sector>,
>> 270 };
>> 271
>> 272 'name' is a text string which will be visible in sysfs. This is
>> 273 part of the userland API so chose it carefully and never change
>> 274 it. The format is standards body-type-variant.
>> 275 E.g. T10-DIF-TYPE1-IP or T13-EPP-0-CRC.
>> 276
>> 277 'generate_fn' generates appropriate integrity metadata (for WRITE).
>> 278
>> 279 'verify_fn' verifies that the data buffer matches the integrity
>> 280 metadata.
>> 281
>> 282 'tuple_size' must be set to match the size of the integrity
>> 283 metadata per sector. I.e. 8 for DIF and EPP.
>> 284
>> 285 'tag_size' must be set to identify how many bytes of tag space
>> 286 are available per hardware sector. For DIF this is either 2 or
>> 287 0 depending on the value of the Control Mode Page ATO bit.
245 288
246 ---------------------------------------------- 289 ----------------------------------------------------------------------
247 290
248 2007-12-24 Martin K. Petersen <martin.petersen@ 291 2007-12-24 Martin K. Petersen <martin.petersen@oracle.com>
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.