€•ª~      Œ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/biovecs”Œ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/biovecs”Œ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/biovecs”Œ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/biovecs”Œ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/biovecs”Œ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/biovecs”Œ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Œ&Immutable biovecs and biovec iterators”h]”hŒ&Immutable biovecs and biovec iterators”…””}”(hh¨hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hh£hžhhŸŒ;/var/lib/git/docbuild/linux/Documentation/block/biovecs.rst”h KubhŒ	paragraph”“”)”}”(hŒ#Kent Overstreet <kmo@daterainc.com>”h]”(hŒKent Overstreet <”…””}”(hh¹hžhhŸNh NubhŒ	reference”“”)”}”(hŒkmo@daterainc.com”h]”hŒkmo@daterainc.com”…””}”(hhÃhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”Œmailto:kmo@daterainc.com”uh1hÁhh¹ubhŒ>”…””}”(hh¹hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khh£hžhubh¸)”}”(hŒâAs of 3.13, biovecs should never be modified after a bio has been submitted.
Instead, we have a new struct bvec_iter which represents a range of a biovec -
the iterator will be modified as the bio is completed, not the biovec.”h]”hŒâAs of 3.13, biovecs should never be modified after a bio has been submitted.
Instead, we have a new struct bvec_iter which represents a range of a biovec -
the iterator will be modified as the bio is completed, not the biovec.”…””}”(hhÝhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khh£hžhubh¸)”}”(hX  More specifically, old code that needed to partially complete a bio would
update bi_sector and bi_size, and advance bi_idx to the next biovec. If it
ended up partway through a biovec, it would increment bv_offset and decrement
bv_len by the number of bytes completed in that biovec.”h]”hX  More specifically, old code that needed to partially complete a bio would
update bi_sector and bi_size, and advance bi_idx to the next biovec. If it
ended up partway through a biovec, it would increment bv_offset and decrement
bv_len by the number of bytes completed in that biovec.”…””}”(hhëhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khh£hžhubh¸)”}”(hXQ  In the new scheme of things, everything that must be mutated in order to
partially complete a bio is segregated into struct bvec_iter: bi_sector,
bi_size and bi_idx have been moved there; and instead of modifying bv_offset
and bv_len, struct bvec_iter has bi_bvec_done, which represents the number of
bytes completed in the current bvec.”h]”hXQ  In the new scheme of things, everything that must be mutated in order to
partially complete a bio is segregated into struct bvec_iter: bi_sector,
bi_size and bi_idx have been moved there; and instead of modifying bv_offset
and bv_len, struct bvec_iter has bi_bvec_done, which represents the number of
bytes completed in the current bvec.”…””}”(hhùhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khh£hžhubh¸)”}”(hŒÆThere are a bunch of new helper macros for hiding the gory details - in
particular, presenting the illusion of partially completed biovecs so that
normal code doesn't have to deal with bi_bvec_done.”h]”hŒÈThere are a bunch of new helper macros for hiding the gory details - in
particular, presenting the illusion of partially completed biovecs so that
normal code doesnâ€™t have to deal with bi_bvec_done.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khh£hžhubhŒblock_quote”“”)”}”(hX@  * Driver code should no longer refer to biovecs directly; we now have
  bio_iovec() and bio_iter_iovec() macros that return literal struct biovecs,
  constructed from the raw biovecs but taking into account bi_bvec_done and
  bi_size.

  bio_for_each_segment() has been updated to take a bvec_iter argument
  instead of an integer (that corresponded to bi_idx); for a lot of code the
  conversion just required changing the types of the arguments to
  bio_for_each_segment().

* Advancing a bvec_iter is done with bio_advance_iter(); bio_advance() is a
  wrapper around bio_advance_iter() that operates on bio->bi_iter, and also
  advances the bio integrity's iter if present.

  There is a lower level advance function - bvec_iter_advance() - which takes
  a pointer to a biovec, not a bio; this is used by the bio integrity code.
”h]”hŒbullet_list”“”)”}”(hhh]”(hŒ	list_item”“”)”}”(hXÌ  Driver code should no longer refer to biovecs directly; we now have
bio_iovec() and bio_iter_iovec() macros that return literal struct biovecs,
constructed from the raw biovecs but taking into account bi_bvec_done and
bi_size.

bio_for_each_segment() has been updated to take a bvec_iter argument
instead of an integer (that corresponded to bi_idx); for a lot of code the
conversion just required changing the types of the arguments to
bio_for_each_segment().
”h]”(h¸)”}”(hŒâDriver code should no longer refer to biovecs directly; we now have
bio_iovec() and bio_iter_iovec() macros that return literal struct biovecs,
constructed from the raw biovecs but taking into account bi_bvec_done and
bi_size.”h]”hŒâDriver code should no longer refer to biovecs directly; we now have
bio_iovec() and bio_iter_iovec() macros that return literal struct biovecs,
constructed from the raw biovecs but taking into account bi_bvec_done and
bi_size.”…””}”(hj&  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khj"  ubh¸)”}”(hŒçbio_for_each_segment() has been updated to take a bvec_iter argument
instead of an integer (that corresponded to bi_idx); for a lot of code the
conversion just required changing the types of the arguments to
bio_for_each_segment().”h]”hŒçbio_for_each_segment() has been updated to take a bvec_iter argument
instead of an integer (that corresponded to bi_idx); for a lot of code the
conversion just required changing the types of the arguments to
bio_for_each_segment().”…””}”(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j  ubj!  )”}”(hXY  Advancing a bvec_iter is done with bio_advance_iter(); bio_advance() is a
wrapper around bio_advance_iter() that operates on bio->bi_iter, and also
advances the bio integrity's iter if present.

There is a lower level advance function - bvec_iter_advance() - which takes
a pointer to a biovec, not a bio; this is used by the bio integrity code.
”h]”(h¸)”}”(hŒÁAdvancing a bvec_iter is done with bio_advance_iter(); bio_advance() is a
wrapper around bio_advance_iter() that operates on bio->bi_iter, and also
advances the bio integrity's iter if present.”h]”hŒÃAdvancing a bvec_iter is done with bio_advance_iter(); bio_advance() is a
wrapper around bio_advance_iter() that operates on bio->bi_iter, and also
advances the bio integrityâ€™s iter if present.”…””}”(hjL  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K$hjH  ubh¸)”}”(hŒ•There is a lower level advance function - bvec_iter_advance() - which takes
a pointer to a biovec, not a bio; this is used by the bio integrity code.”h]”hŒ•There is a lower level advance function - bvec_iter_advance() - which takes
a pointer to a biovec, not a bio; this is used by the bio integrity code.”…””}”(hjZ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K(hjH  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j   hj  ubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ*”uh1j  hŸh¶h Khj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh¶h Khh£hžhubh¸)”}”(hŒ<As of 5.12 bvec segments with zero bv_len are not supported.”h]”hŒ<As of 5.12 bvec segments with zero bv_len are not supported.”…””}”(hj|  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K+hh£hžhubh¢)”}”(hhh]”(h§)”}”(hŒWhat's all this get us?”h]”hŒWhatâ€™s all this get us?”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjŠ  hžhhŸh¶h K.ubh¸)”}”(hŒQHaving a real iterator, and making biovecs immutable, has a number of
advantages:”h]”hŒQHaving a real iterator, and making biovecs immutable, has a number of
advantages:”…””}”(hj›  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K0hjŠ  hžhubj  )”}”(hXd	  * Before, iterating over bios was very awkward when you weren't processing
  exactly one bvec at a time - for example, bio_copy_data() in block/bio.c,
  which copies the contents of one bio into another. Because the biovecs
  wouldn't necessarily be the same size, the old code was tricky convoluted -
  it had to walk two different bios at the same time, keeping both bi_idx and
  and offset into the current biovec for each.

  The new code is much more straightforward - have a look. This sort of
  pattern comes up in a lot of places; a lot of drivers were essentially open
  coding bvec iterators before, and having common implementation considerably
  simplifies a lot of code.

* Before, any code that might need to use the biovec after the bio had been
  completed (perhaps to copy the data somewhere else, or perhaps to resubmit
  it somewhere else if there was an error) had to save the entire bvec array
  - again, this was being done in a fair number of places.

* Biovecs can be shared between multiple bios - a bvec iter can represent an
  arbitrary range of an existing biovec, both starting and ending midway
  through biovecs. This is what enables efficient splitting of arbitrary
  bios. Note that this means we _only_ use bi_size to determine when we've
  reached the end of a bio, not bi_vcnt - and the bio_iovec() macro takes
  bi_size into account when constructing biovecs.

* Splitting bios is now much simpler. The old bio_split() didn't even work on
  bios with more than a single bvec! Now, we can efficiently split arbitrary
  size bios - because the new bio can share the old bio's biovec.

  Care must be taken to ensure the biovec isn't freed while the split bio is
  still using it, in case the original bio completes first, though. Using
  bio_chain() when splitting bios helps with this.

* Submitting partially completed bios is now perfectly fine - this comes up
  occasionally in stacking block drivers and various code (e.g. md and
  bcache) had some ugly workarounds for this.

  It used to be the case that submitting a partially completed bio would work
  fine to _most_ devices, but since accessing the raw bvec array was the
  norm, not all drivers would respect bi_idx and those would break. Now,
  since all drivers _must_ go through the bvec iterator - and have been
  audited to make sure they are - submitting partially completed bios is
  perfectly fine.
”h]”j  )”}”(hhh]”(j!  )”}”(hX˜  Before, iterating over bios was very awkward when you weren't processing
exactly one bvec at a time - for example, bio_copy_data() in block/bio.c,
which copies the contents of one bio into another. Because the biovecs
wouldn't necessarily be the same size, the old code was tricky convoluted -
it had to walk two different bios at the same time, keeping both bi_idx and
and offset into the current biovec for each.

The new code is much more straightforward - have a look. This sort of
pattern comes up in a lot of places; a lot of drivers were essentially open
coding bvec iterators before, and having common implementation considerably
simplifies a lot of code.
”h]”(h¸)”}”(hXž  Before, iterating over bios was very awkward when you weren't processing
exactly one bvec at a time - for example, bio_copy_data() in block/bio.c,
which copies the contents of one bio into another. Because the biovecs
wouldn't necessarily be the same size, the old code was tricky convoluted -
it had to walk two different bios at the same time, keeping both bi_idx and
and offset into the current biovec for each.”h]”hX¢  Before, iterating over bios was very awkward when you werenâ€™t processing
exactly one bvec at a time - for example, bio_copy_data() in block/bio.c,
which copies the contents of one bio into another. Because the biovecs
wouldnâ€™t necessarily be the same size, the old code was tricky convoluted -
it had to walk two different bios at the same time, keeping both bi_idx and
and offset into the current biovec for each.”…””}”(hj´  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K3hj°  ubh¸)”}”(hŒ÷The new code is much more straightforward - have a look. This sort of
pattern comes up in a lot of places; a lot of drivers were essentially open
coding bvec iterators before, and having common implementation considerably
simplifies a lot of code.”h]”hŒ÷The new code is much more straightforward - have a look. This sort of
pattern comes up in a lot of places; a lot of drivers were essentially open
coding bvec iterators before, and having common implementation considerably
simplifies a lot of code.”…””}”(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j­  ubj!  )”}”(hX  Before, any code that might need to use the biovec after the bio had been
completed (perhaps to copy the data somewhere else, or perhaps to resubmit
it somewhere else if there was an error) had to save the entire bvec array
- again, this was being done in a fair number of places.
”h]”h¸)”}”(hX  Before, any code that might need to use the biovec after the bio had been
completed (perhaps to copy the data somewhere else, or perhaps to resubmit
it somewhere else if there was an error) had to save the entire bvec array
- again, this was being done in a fair number of places.”h]”hX  Before, any code that might need to use the biovec after the bio had been
completed (perhaps to copy the data somewhere else, or perhaps to resubmit
it somewhere else if there was an error) had to save the entire bvec array
- again, this was being done in a fair number of places.”…””}”(hjÚ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K?hjÖ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j   hj­  ubj!  )”}”(hXš  Biovecs can be shared between multiple bios - a bvec iter can represent an
arbitrary range of an existing biovec, both starting and ending midway
through biovecs. This is what enables efficient splitting of arbitrary
bios. Note that this means we _only_ use bi_size to determine when we've
reached the end of a bio, not bi_vcnt - and the bio_iovec() macro takes
bi_size into account when constructing biovecs.
”h]”h¸)”}”(hX™  Biovecs can be shared between multiple bios - a bvec iter can represent an
arbitrary range of an existing biovec, both starting and ending midway
through biovecs. This is what enables efficient splitting of arbitrary
bios. Note that this means we _only_ use bi_size to determine when we've
reached the end of a bio, not bi_vcnt - and the bio_iovec() macro takes
bi_size into account when constructing biovecs.”h]”hX›  Biovecs can be shared between multiple bios - a bvec iter can represent an
arbitrary range of an existing biovec, both starting and ending midway
through biovecs. This is what enables efficient splitting of arbitrary
bios. Note that this means we _only_ use bi_size to determine when weâ€™ve
reached the end of a bio, not bi_vcnt - and the bio_iovec() macro takes
bi_size into account when constructing biovecs.”…””}”(hjò  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KDhjî  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j   hj­  ubj!  )”}”(hXœ  Splitting bios is now much simpler. The old bio_split() didn't even work on
bios with more than a single bvec! Now, we can efficiently split arbitrary
size bios - because the new bio can share the old bio's biovec.

Care must be taken to ensure the biovec isn't freed while the split bio is
still using it, in case the original bio completes first, though. Using
bio_chain() when splitting bios helps with this.
”h]”(h¸)”}”(hŒÖSplitting bios is now much simpler. The old bio_split() didn't even work on
bios with more than a single bvec! Now, we can efficiently split arbitrary
size bios - because the new bio can share the old bio's biovec.”h]”hŒÚSplitting bios is now much simpler. The old bio_split() didnâ€™t even work on
bios with more than a single bvec! Now, we can efficiently split arbitrary
size bios - because the new bio can share the old bioâ€™s biovec.”…””}”(hj
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KKhj  ubh¸)”}”(hŒÃCare must be taken to ensure the biovec isn't freed while the split bio is
still using it, in case the original bio completes first, though. Using
bio_chain() when splitting bios helps with this.”h]”hŒÅCare must be taken to ensure the biovec isnâ€™t freed while the split bio is
still using it, in case the original bio completes first, though. Using
bio_chain() when splitting bios helps with this.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KOhj  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j   hj­  ubj!  )”}”(hX3  Submitting partially completed bios is now perfectly fine - this comes up
occasionally in stacking block drivers and various code (e.g. md and
bcache) had some ugly workarounds for this.

It used to be the case that submitting a partially completed bio would work
fine to _most_ devices, but since accessing the raw bvec array was the
norm, not all drivers would respect bi_idx and those would break. Now,
since all drivers _must_ go through the bvec iterator - and have been
audited to make sure they are - submitting partially completed bios is
perfectly fine.
”h]”(h¸)”}”(hŒºSubmitting partially completed bios is now perfectly fine - this comes up
occasionally in stacking block drivers and various code (e.g. md and
bcache) had some ugly workarounds for this.”h]”hŒºSubmitting partially completed bios is now perfectly fine - this comes up
occasionally in stacking block drivers and various code (e.g. md and
bcache) had some ugly workarounds for this.”…””}”(hj0  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KShj,  ubh¸)”}”(hXv  It used to be the case that submitting a partially completed bio would work
fine to _most_ devices, but since accessing the raw bvec array was the
norm, not all drivers would respect bi_idx and those would break. Now,
since all drivers _must_ go through the bvec iterator - and have been
audited to make sure they are - submitting partially completed bios is
perfectly fine.”h]”hXv  It used to be the case that submitting a partially completed bio would work
fine to _most_ devices, but since accessing the raw bvec array was the
norm, not all drivers would respect bi_idx and those would break. Now,
since all drivers _must_ go through the bvec iterator - and have been
audited to make sure they are - submitting partially completed bios is
perfectly fine.”…””}”(hj>  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KWhj,  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j   hj­  ubeh}”(h]”h ]”h"]”h$]”h&]”jt  ju  uh1j  hŸh¶h K3hj©  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh¶h K3hjŠ  hžhubeh}”(h]”Œwhat-s-all-this-get-us”ah ]”h"]”Œwhat's all this get us?”ah$]”h&]”uh1h¡hh£hžhhŸh¶h K.ubh¢)”}”(hhh]”(h§)”}”(hŒOther implications:”h]”hŒOther implications:”…””}”(hji  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjf  hžhhŸh¶h K_ubj  )”}”(hX“  * Almost all usage of bi_idx is now incorrect and has been removed; instead,
  where previously you would have used bi_idx you'd now use a bvec_iter,
  probably passing it to one of the helper macros.

  I.e. instead of using bio_iovec_idx() (or bio->bi_iovec[bio->bi_idx]), you
  now use bio_iter_iovec(), which takes a bvec_iter and returns a
  literal struct bio_vec - constructed on the fly from the raw biovec but
  taking into account bi_bvec_done (and bi_size).

* bi_vcnt can't be trusted or relied upon by driver code - i.e. anything that
  doesn't actually own the bio. The reason is twofold: firstly, it's not
  actually needed for iterating over the bio anymore - we only use bi_size.
  Secondly, when cloning a bio and reusing (a portion of) the original bio's
  biovec, in order to calculate bi_vcnt for the new bio we'd have to iterate
  over all the biovecs in the new bio - which is silly as it's not needed.

  So, don't use bi_vcnt anymore.

* The current interface allows the block layer to split bios as needed, so we
  could eliminate a lot of complexity particularly in stacked drivers. Code
  that creates bios can then create whatever size bios are convenient, and
  more importantly stacked drivers don't have to deal with both their own bio
  size limitations and the limitations of the underlying devices. Thus
  there's no need to define ->merge_bvec_fn() callbacks for individual block
  drivers.
”h]”j  )”}”(hhh]”(j!  )”}”(hXÇ  Almost all usage of bi_idx is now incorrect and has been removed; instead,
where previously you would have used bi_idx you'd now use a bvec_iter,
probably passing it to one of the helper macros.

I.e. instead of using bio_iovec_idx() (or bio->bi_iovec[bio->bi_idx]), you
now use bio_iter_iovec(), which takes a bvec_iter and returns a
literal struct bio_vec - constructed on the fly from the raw biovec but
taking into account bi_bvec_done (and bi_size).
”h]”(h¸)”}”(hŒÂAlmost all usage of bi_idx is now incorrect and has been removed; instead,
where previously you would have used bi_idx you'd now use a bvec_iter,
probably passing it to one of the helper macros.”h]”hŒÄAlmost all usage of bi_idx is now incorrect and has been removed; instead,
where previously you would have used bi_idx youâ€™d now use a bvec_iter,
probably passing it to one of the helper macros.”…””}”(hj‚  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Kahj~  ubh¸)”}”(hX  I.e. instead of using bio_iovec_idx() (or bio->bi_iovec[bio->bi_idx]), you
now use bio_iter_iovec(), which takes a bvec_iter and returns a
literal struct bio_vec - constructed on the fly from the raw biovec but
taking into account bi_bvec_done (and bi_size).”h]”hX  I.e. instead of using bio_iovec_idx() (or bio->bi_iovec[bio->bi_idx]), you
now use bio_iter_iovec(), which takes a bvec_iter and returns a
literal struct bio_vec - constructed on the fly from the raw biovec but
taking into account bi_bvec_done (and bi_size).”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Kehj~  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j   hj{  ubj!  )”}”(hXÜ  bi_vcnt can't be trusted or relied upon by driver code - i.e. anything that
doesn't actually own the bio. The reason is twofold: firstly, it's not
actually needed for iterating over the bio anymore - we only use bi_size.
Secondly, when cloning a bio and reusing (a portion of) the original bio's
biovec, in order to calculate bi_vcnt for the new bio we'd have to iterate
over all the biovecs in the new bio - which is silly as it's not needed.

So, don't use bi_vcnt anymore.
”h]”(h¸)”}”(hX»  bi_vcnt can't be trusted or relied upon by driver code - i.e. anything that
doesn't actually own the bio. The reason is twofold: firstly, it's not
actually needed for iterating over the bio anymore - we only use bi_size.
Secondly, when cloning a bio and reusing (a portion of) the original bio's
biovec, in order to calculate bi_vcnt for the new bio we'd have to iterate
over all the biovecs in the new bio - which is silly as it's not needed.”h]”hXÇ  bi_vcnt canâ€™t be trusted or relied upon by driver code - i.e. anything that
doesnâ€™t actually own the bio. The reason is twofold: firstly, itâ€™s not
actually needed for iterating over the bio anymore - we only use bi_size.
Secondly, when cloning a bio and reusing (a portion of) the original bioâ€™s
biovec, in order to calculate bi_vcnt for the new bio weâ€™d have to iterate
over all the biovecs in the new bio - which is silly as itâ€™s not needed.”…””}”(hj¨  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Kjhj¤  ubh¸)”}”(hŒSo, don't use bi_vcnt anymore.”h]”hŒ So, donâ€™t use bi_vcnt anymore.”…””}”(hj¶  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Kqhj¤  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j   hj{  ubj!  )”}”(hXÄ  The current interface allows the block layer to split bios as needed, so we
could eliminate a lot of complexity particularly in stacked drivers. Code
that creates bios can then create whatever size bios are convenient, and
more importantly stacked drivers don't have to deal with both their own bio
size limitations and the limitations of the underlying devices. Thus
there's no need to define ->merge_bvec_fn() callbacks for individual block
drivers.
”h]”h¸)”}”(hXÃ  The current interface allows the block layer to split bios as needed, so we
could eliminate a lot of complexity particularly in stacked drivers. Code
that creates bios can then create whatever size bios are convenient, and
more importantly stacked drivers don't have to deal with both their own bio
size limitations and the limitations of the underlying devices. Thus
there's no need to define ->merge_bvec_fn() callbacks for individual block
drivers.”h]”hXÇ  The current interface allows the block layer to split bios as needed, so we
could eliminate a lot of complexity particularly in stacked drivers. Code
that creates bios can then create whatever size bios are convenient, and
more importantly stacked drivers donâ€™t have to deal with both their own bio
size limitations and the limitations of the underlying devices. Thus
thereâ€™s no need to define ->merge_bvec_fn() callbacks for individual block
drivers.”…””}”(hjÎ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KshjÊ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j   hj{  ubeh}”(h]”h ]”h"]”h$]”h&]”jt  ju  uh1j  hŸh¶h Kahjw  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh¶h Kahjf  hžhubeh}”(h]”Œother-implications”ah ]”h"]”Œother implications:”ah$]”h&]”uh1h¡hh£hžhhŸh¶h K_ubh¢)”}”(hhh]”(h§)”}”(hŒUsage of helpers:”h]”hŒUsage of helpers:”…””}”(hjù  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjö  hžhhŸh¶h K|ubj  )”}”(hhh]”j!  )”}”(hŒëThe following helpers whose names have the suffix of `_all` can only be used
on non-BIO_CLONED bio. They are usually used by filesystem code. Drivers
shouldn't use them because the bio may have been split before it reached the
driver.
”h]”h¸)”}”(hŒêThe following helpers whose names have the suffix of `_all` can only be used
on non-BIO_CLONED bio. They are usually used by filesystem code. Drivers
shouldn't use them because the bio may have been split before it reached the
driver.”h]”(hŒ5The following helpers whose names have the suffix of ”…””}”(hj  hžhhŸNh NubhŒtitle_reference”“”)”}”(hŒ`_all`”h]”hŒ_all”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj  ubhŒ± can only be used
on non-BIO_CLONED bio. They are usually used by filesystem code. Drivers
shouldnâ€™t use them because the bio may have been split before it reached the
driver.”…””}”(hj  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K~hj
  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j   hj  hžhhŸh¶h Nubah}”(h]”h ]”h"]”h$]”h&]”jt  ju  uh1j  hŸh¶h K~hjö  hžhubhŒliteral_block”“”)”}”(hŒ†bio_for_each_segment_all()
bio_for_each_bvec_all()
bio_first_bvec_all()
bio_first_page_all()
bio_first_folio_all()
bio_last_bvec_all()”h]”hŒ†bio_for_each_segment_all()
bio_for_each_bvec_all()
bio_first_bvec_all()
bio_first_page_all()
bio_first_folio_all()
bio_last_bvec_all()”…””}”hj>  sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1j<  hŸh¶h K…hjö  hžhubj  )”}”(hhh]”(j!  )”}”(hŒÏThe following helpers iterate over single-page segment. The passed 'struct
bio_vec' will contain a single-page IO vector during the iteration::

      bio_for_each_segment()
      bio_for_each_segment_all()
”h]”(h¸)”}”(hŒThe following helpers iterate over single-page segment. The passed 'struct
bio_vec' will contain a single-page IO vector during the iteration::”h]”hŒ’The following helpers iterate over single-page segment. The passed â€˜struct
bio_vecâ€™ will contain a single-page IO vector during the iteration:”…””}”(hjU  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KŒhjQ  ubj=  )”}”(hŒ1bio_for_each_segment()
bio_for_each_segment_all()”h]”hŒ1bio_for_each_segment()
bio_for_each_segment_all()”…””}”hjc  sbah}”(h]”h ]”h"]”h$]”h&]”jL  jM  uh1j<  hŸh¶h KhjQ  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j   hjN  hžhhŸh¶h Nubj!  )”}”(hŒÜThe following helpers iterate over multi-page bvec. The passed 'struct
bio_vec' will contain a multi-page IO vector during the iteration::

      bio_for_each_bvec()
      bio_for_each_bvec_all()
      rq_for_each_bvec()”h]”(h¸)”}”(hŒŠThe following helpers iterate over multi-page bvec. The passed 'struct
bio_vec' will contain a multi-page IO vector during the iteration::”h]”hŒThe following helpers iterate over multi-page bvec. The passed â€˜struct
bio_vecâ€™ will contain a multi-page IO vector during the iteration:”…””}”(hj{  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K’hjw  ubj=  )”}”(hŒ>bio_for_each_bvec()
bio_for_each_bvec_all()
rq_for_each_bvec()”h]”hŒ>bio_for_each_bvec()
bio_for_each_bvec_all()
rq_for_each_bvec()”…””}”hj‰  sbah}”(h]”h ]”h"]”h$]”h&]”jL  jM  uh1j<  hŸh¶h K•hjw  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j   hjN  hžhhŸh¶h Nubeh}”(h]”h ]”h"]”h$]”h&]”jt  ju  uh1j  hŸh¶h KŒhjö  hžhubeh}”(h]”Œusage-of-helpers”ah ]”h"]”Œusage of helpers:”ah$]”h&]”uh1h¡hh£hžhhŸh¶h K|ubeh}”(h]”Œ&immutable-biovecs-and-biovec-iterators”ah ]”h"]”Œ&immutable biovecs and biovec iterators”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­  jc  j`  jó  jð  j¨  j¥  uŒ	nametypes”}”(j°  ‰jc  ‰jó  ‰j¨  ‰uh}”(j­  h£j`  jŠ  jð  jf  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.