€•ˆ      Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ(/translations/zh_CN/block/data-integrity”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ(/translations/zh_TW/block/data-integrity”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ(/translations/it_IT/block/data-integrity”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ(/translations/ja_JP/block/data-integrity”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ(/translations/ko_KR/block/data-integrity”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ(/translations/sp_SP/block/data-integrity”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒData Integrity”h]”hŒData Integrity”…””}”(hh¨hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hh£hžhhŸŒB/var/lib/git/docbuild/linux/Documentation/block/data-integrity.rst”h Kubh¢)”}”(hhh]”(h§)”}”(hŒ1. Introduction”h]”hŒ1. Introduction”…””}”(hhºhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hh·hžhhŸh¶h KubhŒ	paragraph”“”)”}”(hX7  Modern filesystems feature checksumming of data and metadata to
protect against data corruption.  However, the detection of the
corruption is done at read time which could potentially be months
after the data was written.  At that point the original data that the
application tried to write is most likely lost.”h]”hX7  Modern filesystems feature checksumming of data and metadata to
protect against data corruption.  However, the detection of the
corruption is done at read time which could potentially be months
after the data was written.  At that point the original data that the
application tried to write is most likely lost.”…””}”(hhÊhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Khh·hžhubhÉ)”}”(hXr  The solution is to ensure that the disk is actually storing what the
application meant it to.  Recent additions to both the SCSI family
protocols (SBC Data Integrity Field, SCC protection proposal) as well
as SATA/T13 (External Path Protection) try to remedy this by adding
support for appending integrity metadata to an I/O.  The integrity
metadata (or protection information in SCSI terminology) includes a
checksum for each sector as well as an incrementing counter that
ensures the individual sectors are written in the right order.  And
for some protection schemes also that the I/O is written to the right
place on disk.”h]”hXr  The solution is to ensure that the disk is actually storing what the
application meant it to.  Recent additions to both the SCSI family
protocols (SBC Data Integrity Field, SCC protection proposal) as well
as SATA/T13 (External Path Protection) try to remedy this by adding
support for appending integrity metadata to an I/O.  The integrity
metadata (or protection information in SCSI terminology) includes a
checksum for each sector as well as an incrementing counter that
ensures the individual sectors are written in the right order.  And
for some protection schemes also that the I/O is written to the right
place on disk.”…””}”(hhØhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Khh·hžhubhÉ)”}”(hX"  Current storage controllers and devices implement various protective
measures, for instance checksumming and scrubbing.  But these
technologies are working in their own isolated domains or at best
between adjacent nodes in the I/O path.  The interesting thing about
DIF and the other integrity extensions is that the protection format
is well defined and every node in the I/O path can verify the
integrity of the I/O and reject it if corruption is detected.  This
allows not only corruption prevention but also isolation of the point
of failure.”h]”hX"  Current storage controllers and devices implement various protective
measures, for instance checksumming and scrubbing.  But these
technologies are working in their own isolated domains or at best
between adjacent nodes in the I/O path.  The interesting thing about
DIF and the other integrity extensions is that the protection format
is well defined and every node in the I/O path can verify the
integrity of the I/O and reject it if corruption is detected.  This
allows not only corruption prevention but also isolation of the point
of failure.”…””}”(hhæhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Khh·hžhubeh}”(h]”Œintroduction”ah ]”h"]”Œ1. introduction”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒ 2. The Data Integrity Extensions”h]”hŒ 2. The Data Integrity Extensions”…””}”(hhÿhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hhühžhhŸh¶h K$ubhÉ)”}”(hXZ  As written, the protocol extensions only protect the path between
controller and storage device.  However, many controllers actually
allow the operating system to interact with the integrity metadata
(IMD).  We have been working with several FC/SAS HBA vendors to enable
the protection information to be transferred to and from their
controllers.”h]”hXZ  As written, the protocol extensions only protect the path between
controller and storage device.  However, many controllers actually
allow the operating system to interact with the integrity metadata
(IMD).  We have been working with several FC/SAS HBA vendors to enable
the protection information to be transferred to and from their
controllers.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K&hhühžhubhÉ)”}”(hX  The SCSI Data Integrity Field works by appending 8 bytes of protection
information to each sector.  The data + integrity metadata is stored
in 520 byte sectors on disk.  Data + IMD are interleaved when
transferred between the controller and target.  The T13 proposal is
similar.”h]”hX  The SCSI Data Integrity Field works by appending 8 bytes of protection
information to each sector.  The data + integrity metadata is stored
in 520 byte sectors on disk.  Data + IMD are interleaved when
transferred between the controller and target.  The T13 proposal is
similar.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K-hhühžhubhÉ)”}”(hŒäBecause it is highly inconvenient for operating systems to deal with
520 (and 4104) byte sectors, we approached several HBA vendors and
encouraged them to allow separation of the data and integrity metadata
scatter-gather lists.”h]”hŒäBecause it is highly inconvenient for operating systems to deal with
520 (and 4104) byte sectors, we approached several HBA vendors and
encouraged them to allow separation of the data and integrity metadata
scatter-gather lists.”…””}”(hj)  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K3hhühžhubhÉ)”}”(hŒ¶The controller will interleave the buffers on write and split them on
read.  This means that Linux can DMA the data buffers to and from
host memory without changes to the page cache.”h]”hŒ¶The controller will interleave the buffers on write and split them on
read.  This means that Linux can DMA the data buffers to and from
host memory without changes to the page cache.”…””}”(hj7  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K8hhühžhubhÉ)”}”(hXs  Also, the 16-bit CRC checksum mandated by both the SCSI and SATA specs
is somewhat heavy to compute in software.  Benchmarks found that
calculating this checksum had a significant impact on system
performance for a number of workloads.  Some controllers allow a
lighter-weight checksum to be used when interfacing with the operating
system.  Emulex, for instance, supports the TCP/IP checksum instead.
The IP checksum received from the OS is converted to the 16-bit CRC
when writing and vice versa.  This allows the integrity metadata to be
generated by Linux or the application at very low cost (comparable to
software RAID5).”h]”hXs  Also, the 16-bit CRC checksum mandated by both the SCSI and SATA specs
is somewhat heavy to compute in software.  Benchmarks found that
calculating this checksum had a significant impact on system
performance for a number of workloads.  Some controllers allow a
lighter-weight checksum to be used when interfacing with the operating
system.  Emulex, for instance, supports the TCP/IP checksum instead.
The IP checksum received from the OS is converted to the 16-bit CRC
when writing and vice versa.  This allows the integrity metadata to be
generated by Linux or the application at very low cost (comparable to
software RAID5).”…””}”(hjE  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K<hhühžhubhÉ)”}”(hŒíThe IP checksum is weaker than the CRC in terms of detecting bit
errors.  However, the strength is really in the separation of the data
buffers and the integrity metadata.  These two distinct buffers must
match up for an I/O to complete.”h]”hŒíThe IP checksum is weaker than the CRC in terms of detecting bit
errors.  However, the strength is really in the separation of the data
buffers and the integrity metadata.  These two distinct buffers must
match up for an I/O to complete.”…””}”(hjS  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KGhhühžhubhÉ)”}”(hXF  The separation of the data and integrity metadata buffers as well as
the choice in checksums is referred to as the Data Integrity
Extensions.  As these extensions are outside the scope of the protocol
bodies (T10, T13), Oracle and its partners are trying to standardize
them within the Storage Networking Industry Association.”h]”hXF  The separation of the data and integrity metadata buffers as well as
the choice in checksums is referred to as the Data Integrity
Extensions.  As these extensions are outside the scope of the protocol
bodies (T10, T13), Oracle and its partners are trying to standardize
them within the Storage Networking Industry Association.”…””}”(hja  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KLhhühžhubeh}”(h]”Œthe-data-integrity-extensions”ah ]”h"]”Œ 2. the data integrity extensions”ah$]”h&]”uh1h¡hh£hžhhŸh¶h K$ubh¢)”}”(hhh]”(h§)”}”(hŒ3. Kernel Changes”h]”hŒ3. Kernel Changes”…””}”(hjz  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjw  hžhhŸh¶h KSubhÉ)”}”(hŒThe data integrity framework in Linux enables protection information
to be pinned to I/Os and sent to/received from controllers that
support it.”h]”hŒThe data integrity framework in Linux enables protection information
to be pinned to I/Os and sent to/received from controllers that
support it.”…””}”(hjˆ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KUhjw  hžhubhÉ)”}”(hX3  The advantage to the integrity extensions in SCSI and SATA is that
they enable us to protect the entire path from application to storage
device.  However, at the same time this is also the biggest
disadvantage. It means that the protection information must be in a
format that can be understood by the disk.”h]”hX3  The advantage to the integrity extensions in SCSI and SATA is that
they enable us to protect the entire path from application to storage
device.  However, at the same time this is also the biggest
disadvantage. It means that the protection information must be in a
format that can be understood by the disk.”…””}”(hj–  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KYhjw  hžhubhÉ)”}”(hX	  Generally Linux/POSIX applications are agnostic to the intricacies of
the storage devices they are accessing.  The virtual filesystem switch
and the block layer make things like hardware sector size and
transport protocols completely transparent to the application.”h]”hX	  Generally Linux/POSIX applications are agnostic to the intricacies of
the storage devices they are accessing.  The virtual filesystem switch
and the block layer make things like hardware sector size and
transport protocols completely transparent to the application.”…””}”(hj¤  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K_hjw  hžhubhÉ)”}”(hX,  However, this level of detail is required when preparing the
protection information to send to a disk.  Consequently, the very
concept of an end-to-end protection scheme is a layering violation.
It is completely unreasonable for an application to be aware whether
it is accessing a SCSI or SATA disk.”h]”hX,  However, this level of detail is required when preparing the
protection information to send to a disk.  Consequently, the very
concept of an end-to-end protection scheme is a layering violation.
It is completely unreasonable for an application to be aware whether
it is accessing a SCSI or SATA disk.”…””}”(hj²  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kdhjw  hžhubhÉ)”}”(hŒíThe data integrity support implemented in Linux attempts to hide this
from the application.  As far as the application (and to some extent
the kernel) is concerned, the integrity metadata is opaque information
that's attached to the I/O.”h]”hŒïThe data integrity support implemented in Linux attempts to hide this
from the application.  As far as the application (and to some extent
the kernel) is concerned, the integrity metadata is opaque information
thatâ€™s attached to the I/O.”…””}”(hjÀ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kjhjw  hžhubhÉ)”}”(hXA  The current implementation allows the block layer to automatically
generate the protection information for any I/O.  Eventually the
intent is to move the integrity metadata calculation to userspace for
user data.  Metadata and other I/O that originates within the kernel
will still use the automatic generation interface.”h]”hXA  The current implementation allows the block layer to automatically
generate the protection information for any I/O.  Eventually the
intent is to move the integrity metadata calculation to userspace for
user data.  Metadata and other I/O that originates within the kernel
will still use the automatic generation interface.”…””}”(hjÎ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kohjw  hžhubhÉ)”}”(hXÀ  Some storage devices allow each hardware sector to be tagged with a
16-bit value.  The owner of this tag space is the owner of the block
device.  I.e. the filesystem in most cases.  The filesystem can use
this extra space to tag sectors as they see fit.  Because the tag
space is limited, the block interface allows tagging bigger chunks by
way of interleaving.  This way, 8*16 bits of information can be
attached to a typical 4KB filesystem block.”h]”hXÀ  Some storage devices allow each hardware sector to be tagged with a
16-bit value.  The owner of this tag space is the owner of the block
device.  I.e. the filesystem in most cases.  The filesystem can use
this extra space to tag sectors as they see fit.  Because the tag
space is limited, the block interface allows tagging bigger chunks by
way of interleaving.  This way, 8*16 bits of information can be
attached to a typical 4KB filesystem block.”…””}”(hjÜ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kuhjw  hžhubhÉ)”}”(hŒ¦This also means that applications such as fsck and mkfs will need
access to manipulate the tags from user space.  A passthrough
interface for this is being worked on.”h]”hŒ¦This also means that applications such as fsck and mkfs will need
access to manipulate the tags from user space.  A passthrough
interface for this is being worked on.”…””}”(hjê  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K}hjw  hžhubeh}”(h]”Œkernel-changes”ah ]”h"]”Œ3. kernel changes”ah$]”h&]”uh1h¡hh£hžhhŸh¶h KSubh¢)”}”(hhh]”(h§)”}”(hŒ%4. Block Layer Implementation Details”h]”hŒ%4. Block Layer Implementation Details”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj   hžhhŸh¶h Kƒubh¢)”}”(hhh]”(h§)”}”(hŒ4.1 Bio”h]”hŒ4.1 Bio”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj  hžhhŸh¶h K†ubhÉ)”}”(hXs  The data integrity patches add a new field to struct bio when
CONFIG_BLK_DEV_INTEGRITY is enabled.  bio_integrity(bio) returns a
pointer to a struct bip which contains the bio integrity payload.
Essentially a bip is a trimmed down struct bio which holds a bio_vec
containing the integrity metadata and the required housekeeping
information (bvec pool, vector count, etc.)”h]”hXs  The data integrity patches add a new field to struct bio when
CONFIG_BLK_DEV_INTEGRITY is enabled.  bio_integrity(bio) returns a
pointer to a struct bip which contains the bio integrity payload.
Essentially a bip is a trimmed down struct bio which holds a bio_vec
containing the integrity metadata and the required housekeeping
information (bvec pool, vector count, etc.)”…””}”(hj"  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kˆhj  hžhubhÉ)”}”(hŒ˜A kernel subsystem can enable data integrity protection on a bio by
calling bio_integrity_alloc(bio).  This will allocate and attach the
bip to the bio.”h]”hŒ˜A kernel subsystem can enable data integrity protection on a bio by
calling bio_integrity_alloc(bio).  This will allocate and attach the
bip to the bio.”…””}”(hj0  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Khj  hžhubhÉ)”}”(hŒkIndividual pages containing integrity metadata can subsequently be
attached using bio_integrity_add_page().”h]”hŒkIndividual pages containing integrity metadata can subsequently be
attached using bio_integrity_add_page().”…””}”(hj>  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K“hj  hžhubhÉ)”}”(hŒ+bio_free() will automatically free the bip.”h]”hŒ+bio_free() will automatically free the bip.”…””}”(hjL  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K–hj  hžhubeh}”(h]”Œbio”ah ]”h"]”Œ4.1 bio”ah$]”h&]”uh1h¡hj   hžhhŸh¶h K†ubh¢)”}”(hhh]”(h§)”}”(hŒ4.2 Block Device”h]”hŒ4.2 Block Device”…””}”(hje  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjb  hžhhŸh¶h KšubhÉ)”}”(hŒoBlock devices can set up the integrity information in the integrity
sub-struture of the queue_limits structure.”h]”hŒoBlock devices can set up the integrity information in the integrity
sub-struture of the queue_limits structure.”…””}”(hjs  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kœhjb  hžhubhÉ)”}”(hX  Layered block devices will need to pick a profile that's appropriate
for all subdevices.  queue_limits_stack_integrity() can help with that.  DM
and MD linear, RAID0 and RAID1 are currently supported.  RAID4/5/6
will require extra work due to the application tag.”h]”hX	  Layered block devices will need to pick a profile thatâ€™s appropriate
for all subdevices.  queue_limits_stack_integrity() can help with that.  DM
and MD linear, RAID0 and RAID1 are currently supported.  RAID4/5/6
will require extra work due to the application tag.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KŸhjb  hžhubeh}”(h]”Œblock-device”ah ]”h"]”Œ4.2 block device”ah$]”h&]”uh1h¡hj   hžhhŸh¶h Kšubeh}”(h]”Œ"block-layer-implementation-details”ah ]”h"]”Œ%4. block layer implementation details”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kƒubh¢)”}”(hhh]”(h§)”}”(hŒ5.0 Block Layer Integrity API”h]”hŒ5.0 Block Layer Integrity API”…””}”(hj¢  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjŸ  hžhhŸh¶h K¦ubh¢)”}”(hhh]”(h§)”}”(hŒ5.1 Normal Filesystem”h]”hŒ5.1 Normal Filesystem”…””}”(hj³  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj°  hžhhŸh¶h K©ubhŒblock_quote”“”)”}”(hXÍ  The normal filesystem is unaware that the underlying block device
is capable of sending/receiving integrity metadata.  The IMD will
be automatically generated by the block layer at submit_bio() time
in case of a WRITE.  A READ request will cause the I/O integrity
to be verified upon completion.

IMD generation and verification can be toggled using the::

  /sys/block/<bdev>/integrity/write_generate

and::

  /sys/block/<bdev>/integrity/read_verify

flags.

”h]”(hÉ)”}”(hX'  The normal filesystem is unaware that the underlying block device
is capable of sending/receiving integrity metadata.  The IMD will
be automatically generated by the block layer at submit_bio() time
in case of a WRITE.  A READ request will cause the I/O integrity
to be verified upon completion.”h]”hX'  The normal filesystem is unaware that the underlying block device
is capable of sending/receiving integrity metadata.  The IMD will
be automatically generated by the block layer at submit_bio() time
in case of a WRITE.  A READ request will cause the I/O integrity
to be verified upon completion.”…””}”(hjÇ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K«hjÃ  ubhÉ)”}”(hŒ:IMD generation and verification can be toggled using the::”h]”hŒ9IMD generation and verification can be toggled using the:”…””}”(hjÕ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K±hjÃ  ubhŒliteral_block”“”)”}”(hŒ*/sys/block/<bdev>/integrity/write_generate”h]”hŒ*/sys/block/<bdev>/integrity/write_generate”…””}”hjå  sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1jã  hŸh¶h K³hjÃ  ubhÉ)”}”(hŒand::”h]”hŒand:”…””}”(hjõ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KµhjÃ  ubjä  )”}”(hŒ'/sys/block/<bdev>/integrity/read_verify”h]”hŒ'/sys/block/<bdev>/integrity/read_verify”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”jó  jô  uh1jã  hŸh¶h K·hjÃ  ubhÉ)”}”(hŒflags.”h]”hŒflags.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K¹hjÃ  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jÁ  hŸh¶h K«hj°  hžhubeh}”(h]”Œnormal-filesystem”ah ]”h"]”Œ5.1 normal filesystem”ah$]”h&]”uh1h¡hjŸ  hžhhŸh¶h K©ubh¢)”}”(hhh]”(h§)”}”(hŒ5.2 Integrity-Aware Filesystem”h]”hŒ5.2 Integrity-Aware Filesystem”…””}”(hj0  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj-  hžhhŸh¶h K½ubjÂ  )”}”(hXT  A filesystem that is integrity-aware can prepare I/Os with IMD
attached.  It can also use the application tag space if this is
supported by the block device.


`bool bio_integrity_prep(bio);`

  To generate IMD for WRITE and to set up buffers for READ, the
  filesystem must call bio_integrity_prep(bio).

  Prior to calling this function, the bio data direction and start
  sector must be set, and the bio should have all data pages
  added.  It is up to the caller to ensure that the bio does not
  change while I/O is in progress.
  Complete bio with error if prepare failed for some reason.

”h]”(hÉ)”}”(hŒA filesystem that is integrity-aware can prepare I/Os with IMD
attached.  It can also use the application tag space if this is
supported by the block device.”h]”hŒA filesystem that is integrity-aware can prepare I/Os with IMD
attached.  It can also use the application tag space if this is
supported by the block device.”…””}”(hjB  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K¿hj>  ubhÉ)”}”(hŒ`bool bio_integrity_prep(bio);`”h]”hŒtitle_reference”“”)”}”(hjR  h]”hŒbool bio_integrity_prep(bio);”…””}”(hjV  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jT  hjP  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KÄhj>  ubjÂ  )”}”(hX…  To generate IMD for WRITE and to set up buffers for READ, the
filesystem must call bio_integrity_prep(bio).

Prior to calling this function, the bio data direction and start
sector must be set, and the bio should have all data pages
added.  It is up to the caller to ensure that the bio does not
change while I/O is in progress.
Complete bio with error if prepare failed for some reason.

”h]”(hÉ)”}”(hŒkTo generate IMD for WRITE and to set up buffers for READ, the
filesystem must call bio_integrity_prep(bio).”h]”hŒkTo generate IMD for WRITE and to set up buffers for READ, the
filesystem must call bio_integrity_prep(bio).”…””}”(hjm  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KÆhji  ubhÉ)”}”(hX  Prior to calling this function, the bio data direction and start
sector must be set, and the bio should have all data pages
added.  It is up to the caller to ensure that the bio does not
change while I/O is in progress.
Complete bio with error if prepare failed for some reason.”h]”hX  Prior to calling this function, the bio data direction and start
sector must be set, and the bio should have all data pages
added.  It is up to the caller to ensure that the bio does not
change while I/O is in progress.
Complete bio with error if prepare failed for some reason.”…””}”(hj{  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KÉhji  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jÁ  hŸh¶h KÆhj>  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jÁ  hŸh¶h K¿hj-  hžhubeh}”(h]”Œintegrity-aware-filesystem”ah ]”h"]”Œ5.2 integrity-aware filesystem”ah$]”h&]”uh1h¡hjŸ  hžhhŸh¶h K½ubh¢)”}”(hhh]”(h§)”}”(hŒ'5.3 Passing Existing Integrity Metadata”h]”hŒ'5.3 Passing Existing Integrity Metadata”…””}”(hj   hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj  hžhhŸh¶h KÑubjÂ  )”}”(hX}  Filesystems that either generate their own integrity metadata or
are capable of transferring IMD from user space can use the
following calls:


`struct bip * bio_integrity_alloc(bio, gfp_mask, nr_pages);`

  Allocates the bio integrity payload and hangs it off of the bio.
  nr_pages indicate how many pages of protection data need to be
  stored in the integrity bio_vec list (similar to bio_alloc()).

  The integrity payload will be freed at bio_free() time.


`int bio_integrity_add_page(bio, page, len, offset);`

  Attaches a page containing integrity metadata to an existing
  bio.  The bio must have an existing bip,
  i.e. bio_integrity_alloc() must have been called.  For a WRITE,
  the integrity metadata in the pages must be in a format
  understood by the target device with the notable exception that
  the sector numbers will be remapped as the request traverses the
  I/O stack.  This implies that the pages added using this call
  will be modified during I/O!  The first reference tag in the
  integrity metadata must have a value of bip->bip_sector.

  Pages can be added using bio_integrity_add_page() as long as
  there is room in the bip bio_vec array (nr_pages).

  Upon completion of a READ operation, the attached pages will
  contain the integrity metadata received from the storage device.
  It is up to the receiver to process them and verify data
  integrity upon completion.

”h]”(hÉ)”}”(hŒFilesystems that either generate their own integrity metadata or
are capable of transferring IMD from user space can use the
following calls:”h]”hŒFilesystems that either generate their own integrity metadata or
are capable of transferring IMD from user space can use the
following calls:”…””}”(hj²  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KÓhj®  ubhÉ)”}”(hŒ<`struct bip * bio_integrity_alloc(bio, gfp_mask, nr_pages);`”h]”jU  )”}”(hjÂ  h]”hŒ:struct bip * bio_integrity_alloc(bio, gfp_mask, nr_pages);”…””}”(hjÄ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jT  hjÀ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KØhj®  ubjÂ  )”}”(hŒùAllocates the bio integrity payload and hangs it off of the bio.
nr_pages indicate how many pages of protection data need to be
stored in the integrity bio_vec list (similar to bio_alloc()).

The integrity payload will be freed at bio_free() time.

”h]”(hÉ)”}”(hŒ¾Allocates the bio integrity payload and hangs it off of the bio.
nr_pages indicate how many pages of protection data need to be
stored in the integrity bio_vec list (similar to bio_alloc()).”h]”hŒ¾Allocates the bio integrity payload and hangs it off of the bio.
nr_pages indicate how many pages of protection data need to be
stored in the integrity bio_vec list (similar to bio_alloc()).”…””}”(hjÛ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KÚhj×  ubhÉ)”}”(hŒ7The integrity payload will be freed at bio_free() time.”h]”hŒ7The integrity payload will be freed at bio_free() time.”…””}”(hjé  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KÞhj×  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jÁ  hŸh¶h KÚhj®  ubhÉ)”}”(hŒ5`int bio_integrity_add_page(bio, page, len, offset);`”h]”jU  )”}”(hjÿ  h]”hŒ3int bio_integrity_add_page(bio, page, len, offset);”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jT  hjý  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Káhj®  ubjÂ  )”}”(hXX  Attaches a page containing integrity metadata to an existing
bio.  The bio must have an existing bip,
i.e. bio_integrity_alloc() must have been called.  For a WRITE,
the integrity metadata in the pages must be in a format
understood by the target device with the notable exception that
the sector numbers will be remapped as the request traverses the
I/O stack.  This implies that the pages added using this call
will be modified during I/O!  The first reference tag in the
integrity metadata must have a value of bip->bip_sector.

Pages can be added using bio_integrity_add_page() as long as
there is room in the bip bio_vec array (nr_pages).

Upon completion of a READ operation, the attached pages will
contain the integrity metadata received from the storage device.
It is up to the receiver to process them and verify data
integrity upon completion.

”h]”(hÉ)”}”(hX  Attaches a page containing integrity metadata to an existing
bio.  The bio must have an existing bip,
i.e. bio_integrity_alloc() must have been called.  For a WRITE,
the integrity metadata in the pages must be in a format
understood by the target device with the notable exception that
the sector numbers will be remapped as the request traverses the
I/O stack.  This implies that the pages added using this call
will be modified during I/O!  The first reference tag in the
integrity metadata must have a value of bip->bip_sector.”h]”hX  Attaches a page containing integrity metadata to an existing
bio.  The bio must have an existing bip,
i.e. bio_integrity_alloc() must have been called.  For a WRITE,
the integrity metadata in the pages must be in a format
understood by the target device with the notable exception that
the sector numbers will be remapped as the request traverses the
I/O stack.  This implies that the pages added using this call
will be modified during I/O!  The first reference tag in the
integrity metadata must have a value of bip->bip_sector.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kãhj  ubhÉ)”}”(hŒoPages can be added using bio_integrity_add_page() as long as
there is room in the bip bio_vec array (nr_pages).”h]”hŒoPages can be added using bio_integrity_add_page() as long as
there is room in the bip bio_vec array (nr_pages).”…””}”(hj&  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kíhj  ubhÉ)”}”(hŒÑUpon completion of a READ operation, the attached pages will
contain the integrity metadata received from the storage device.
It is up to the receiver to process them and verify data
integrity upon completion.”h]”hŒÑUpon completion of a READ operation, the attached pages will
contain the integrity metadata received from the storage device.
It is up to the receiver to process them and verify data
integrity upon completion.”…””}”(hj4  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kðhj  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jÁ  hŸh¶h Kãhj®  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jÁ  hŸh¶h KÓhj  hžhubhŒ
transition”“”)”}”(hŒF----------------------------------------------------------------------”h]”h}”(h]”h ]”h"]”h$]”h&]”uh1jN  hŸh¶h Köhj  hžhubhÉ)”}”(hŒ:2007-12-24 Martin K. Petersen <martin.petersen@oracle.com>”h]”(hŒ2007-12-24 Martin K. Petersen <”…””}”(hjZ  hžhhŸNh NubhŒ	reference”“”)”}”(hŒmartin.petersen@oracle.com”h]”hŒmartin.petersen@oracle.com”…””}”(hjd  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”Œ!mailto:martin.petersen@oracle.com”uh1jb  hjZ  ubhŒ>”…””}”(hjZ  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Køhj  hžhubeh}”(h]”Œ#passing-existing-integrity-metadata”ah ]”h"]”Œ'5.3 passing existing integrity metadata”ah$]”h&]”uh1h¡hjŸ  hžhhŸh¶h KÑubeh}”(h]”Œblock-layer-integrity-api”ah ]”h"]”Œ5.0 block layer integrity api”ah$]”h&]”uh1h¡hh£hžhhŸh¶h K¦ubeh}”(h]”Œdata-integrity”ah ]”h"]”Œdata integrity”ah$]”h&]”uh1h¡hhhžhhŸh¶h Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h¶uh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(h¦NŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”Œentry”Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”j¹  Œerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h¶Œ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”Œnameids”}”(j“  j  hùhöjt  jq  jý  jú  jœ  j™  j_  j\  j”  j‘  j‹  jˆ  j*  j'  jš  j—  jƒ  j€  uŒ	nametypes”}”(j“  ‰hù‰jt  ‰jý  ‰jœ  ‰j_  ‰j”  ‰j‹  ‰j*  ‰jš  ‰jƒ  ‰uh}”(j  h£höh·jq  hüjú  jw  j™  j   j\  j  j‘  jb  jˆ  jŸ  j'  j°  j—  j-  j€  j  uŒfootnote_refs”}”Œcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”Œ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”Œtransformer”NŒinclude_log”]”Œ
decoration”Nhžhub.