€•úI      Œ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”Œ0/translations/zh_CN/livepatch/cumulative-patches”Œ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”Œ0/translations/zh_TW/livepatch/cumulative-patches”Œ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”Œ0/translations/it_IT/livepatch/cumulative-patches”Œ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”Œ0/translations/ja_JP/livepatch/cumulative-patches”Œ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”Œ0/translations/ko_KR/livepatch/cumulative-patches”Œ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”Œ0/translations/sp_SP/livepatch/cumulative-patches”Œ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Œ#Atomic Replace & Cumulative Patches”h]”hŒ#Atomic Replace & Cumulative Patches”…””}”(hh¨hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hh£hžhhŸŒJ/var/lib/git/docbuild/linux/Documentation/livepatch/cumulative-patches.rst”h KubhŒ	paragraph”“”)”}”(hX  There might be dependencies between livepatches. If multiple patches need
to do different changes to the same function(s) then we need to define
an order in which the patches will be installed. And function implementations
from any newer livepatch must be done on top of the older ones.”h]”hX  There might be dependencies between livepatches. If multiple patches need
to do different changes to the same function(s) then we need to define
an order in which the patches will be installed. And function implementations
from any newer livepatch must be done on top of the older ones.”…””}”(hh¹hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khh£hžhubh¸)”}”(hŒuThis might become a maintenance nightmare. Especially when more patches
modified the same function in different ways.”h]”hŒuThis might become a maintenance nightmare. Especially when more patches
modified the same function in different ways.”…””}”(hhÇhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K
hh£hžhubh¸)”}”(hŒãAn elegant solution comes with the feature called "Atomic Replace". It allows
creation of so called "Cumulative Patches". They include all wanted changes
from all older livepatches and completely replace them in one transition.”h]”hŒëAn elegant solution comes with the feature called â€œAtomic Replaceâ€. It allows
creation of so called â€œCumulative Patchesâ€. They include all wanted changes
from all older livepatches and completely replace them in one transition.”…””}”(hhÕhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khh£hžhubh¢)”}”(hhh]”(h§)”}”(hŒUsage”h]”hŒUsage”…””}”(hhæhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hhãhžhhŸh¶h Kubh¸)”}”(hŒ^The atomic replace can be enabled by setting "replace" flag in struct klp_patch,
for example::”h]”hŒaThe atomic replace can be enabled by setting â€œreplaceâ€ flag in struct klp_patch,
for example:”…””}”(hhôhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KhhãhžhubhŒliteral_block”“”)”}”(hŒostatic struct klp_patch patch = {
        .mod = THIS_MODULE,
        .objs = objs,
        .replace = true,
};”h]”hŒostatic struct klp_patch patch = {
        .mod = THIS_MODULE,
        .objs = objs,
        .replace = true,
};”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1j  hŸh¶h Khhãhžhubh¸)”}”(hŒ—All processes are then migrated to use the code only from the new patch.
Once the transition is finished, all older patches are automatically
disabled.”h]”hŒ—All processes are then migrated to use the code only from the new patch.
Once the transition is finished, all older patches are automatically
disabled.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khhãhžhubh¸)”}”(hŒqFtrace handlers are transparently removed from functions that are no
longer modified by the new cumulative patch.”h]”hŒqFtrace handlers are transparently removed from functions that are no
longer modified by the new cumulative patch.”…””}”(hj"  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K!hhãhžhubh¸)”}”(hŒ²As a result, the livepatch authors might maintain sources only for one
cumulative patch. It helps to keep the patch consistent while adding or
removing various fixes or features.”h]”hŒ²As a result, the livepatch authors might maintain sources only for one
cumulative patch. It helps to keep the patch consistent while adding or
removing various fixes or features.”…””}”(hj0  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K$hhãhžhubh¸)”}”(hXS  Users could keep only the last patch installed on the system after
the transition to has finished. It helps to clearly see what code is
actually in use. Also the livepatch might then be seen as a "normal"
module that modifies the kernel behavior. The only difference is that
it can be updated at runtime without breaking its functionality.”h]”hXW  Users could keep only the last patch installed on the system after
the transition to has finished. It helps to clearly see what code is
actually in use. Also the livepatch might then be seen as a â€œnormalâ€
module that modifies the kernel behavior. The only difference is that
it can be updated at runtime without breaking its functionality.”…””}”(hj>  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K(hhãhžhubeh}”(h]”Œusage”ah ]”h"]”Œusage”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒFeatures”h]”hŒFeatures”…””}”(hjW  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjT  hžhhŸh¶h K0ubh¸)”}”(hŒThe atomic replace allows:”h]”hŒThe atomic replace allows:”…””}”(hje  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K2hjT  hžhubhŒblock_quote”“”)”}”(hX  - Atomically revert some functions in a previous patch while
  upgrading other functions.

- Remove eventual performance impact caused by core redirection
  for functions that are no longer patched.

- Decrease user confusion about dependencies between livepatches.

”h]”hŒbullet_list”“”)”}”(hhh]”(hŒ	list_item”“”)”}”(hŒVAtomically revert some functions in a previous patch while
upgrading other functions.
”h]”h¸)”}”(hŒUAtomically revert some functions in a previous patch while
upgrading other functions.”h]”hŒUAtomically revert some functions in a previous patch while
upgrading other functions.”…””}”(hj„  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K4hj€  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j~  hj{  ubj  )”}”(hŒhRemove eventual performance impact caused by core redirection
for functions that are no longer patched.
”h]”h¸)”}”(hŒgRemove eventual performance impact caused by core redirection
for functions that are no longer patched.”h]”hŒgRemove eventual performance impact caused by core redirection
for functions that are no longer patched.”…””}”(hjœ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K7hj˜  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j~  hj{  ubj  )”}”(hŒADecrease user confusion about dependencies between livepatches.

”h]”h¸)”}”(hŒ?Decrease user confusion about dependencies between livepatches.”h]”hŒ?Decrease user confusion about dependencies between livepatches.”…””}”(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{  ubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ-”uh1jy  hŸh¶h K4hju  ubah}”(h]”h ]”h"]”h$]”h&]”uh1js  hŸh¶h K4hjT  hžhubeh}”(h]”Œfeatures”ah ]”h"]”Œfeatures”ah$]”h&]”uh1h¡hh£hžhhŸh¶h K0ubh¢)”}”(hhh]”(h§)”}”(hŒLimitations:”h]”hŒLimitations:”…””}”(hjá  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjÞ  hžhhŸh¶h K>ubjt  )”}”(hXý  - Once the operation finishes, there is no straightforward way
  to reverse it and restore the replaced patches atomically.

  A good practice is to set .replace flag in any released livepatch.
  Then re-adding an older livepatch is equivalent to downgrading
  to that patch. This is safe as long as the livepatches do _not_ do
  extra modifications in (un)patching callbacks or in the module_init()
  or module_exit() functions, see below.

  Also note that the replaced patch can be removed and loaded again
  only when the transition was not forced.


- Only the (un)patching callbacks from the _new_ cumulative livepatch are
  executed. Any callbacks from the replaced patches are ignored.

  In other words, the cumulative patch is responsible for doing any actions
  that are necessary to properly replace any older patch.

  As a result, it might be dangerous to replace newer cumulative patches by
  older ones. The old livepatches might not provide the necessary callbacks.

  This might be seen as a limitation in some scenarios. But it makes life
  easier in many others. Only the new cumulative livepatch knows what
  fixes/features are added/removed and what special actions are necessary
  for a smooth transition.

  In any case, it would be a nightmare to think about the order of
  the various callbacks and their interactions if the callbacks from all
  enabled patches were called.


- There is no special handling of shadow variables. Livepatch authors
  must create their own rules how to pass them from one cumulative
  patch to the other. Especially that they should not blindly remove
  them in module_exit() functions.

  A good practice might be to remove shadow variables in the post-unpatch
  callback. It is called only when the livepatch is properly disabled.”h]”jz  )”}”(hhh]”(j  )”}”(hX  Once the operation finishes, there is no straightforward way
to reverse it and restore the replaced patches atomically.

A good practice is to set .replace flag in any released livepatch.
Then re-adding an older livepatch is equivalent to downgrading
to that patch. This is safe as long as the livepatches do _not_ do
extra modifications in (un)patching callbacks or in the module_init()
or module_exit() functions, see below.

Also note that the replaced patch can be removed and loaded again
only when the transition was not forced.

”h]”(h¸)”}”(hŒwOnce the operation finishes, there is no straightforward way
to reverse it and restore the replaced patches atomically.”h]”hŒwOnce the operation finishes, there is no straightforward way
to reverse it and restore the replaced patches atomically.”…””}”(hjú  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K@hjö  ubh¸)”}”(hX1  A good practice is to set .replace flag in any released livepatch.
Then re-adding an older livepatch is equivalent to downgrading
to that patch. This is safe as long as the livepatches do _not_ do
extra modifications in (un)patching callbacks or in the module_init()
or module_exit() functions, see below.”h]”hX1  A good practice is to set .replace flag in any released livepatch.
Then re-adding an older livepatch is equivalent to downgrading
to that patch. This is safe as long as the livepatches do _not_ do
extra modifications in (un)patching callbacks or in the module_init()
or module_exit() functions, see below.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KChjö  ubh¸)”}”(hŒjAlso note that the replaced patch can be removed and loaded again
only when the transition was not forced.”h]”hŒjAlso note that the replaced patch can be removed and loaded again
only when the transition was not forced.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KIhjö  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j~  hjó  ubj  )”}”(hX5  Only the (un)patching callbacks from the _new_ cumulative livepatch are
executed. Any callbacks from the replaced patches are ignored.

In other words, the cumulative patch is responsible for doing any actions
that are necessary to properly replace any older patch.

As a result, it might be dangerous to replace newer cumulative patches by
older ones. The old livepatches might not provide the necessary callbacks.

This might be seen as a limitation in some scenarios. But it makes life
easier in many others. Only the new cumulative livepatch knows what
fixes/features are added/removed and what special actions are necessary
for a smooth transition.

In any case, it would be a nightmare to think about the order of
the various callbacks and their interactions if the callbacks from all
enabled patches were called.

”h]”(h¸)”}”(hŒ†Only the (un)patching callbacks from the _new_ cumulative livepatch are
executed. Any callbacks from the replaced patches are ignored.”h]”hŒ†Only the (un)patching callbacks from the _new_ cumulative livepatch are
executed. Any callbacks from the replaced patches are ignored.”…””}”(hj.  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KMhj*  ubh¸)”}”(hŒIn other words, the cumulative patch is responsible for doing any actions
that are necessary to properly replace any older patch.”h]”hŒIn other words, the cumulative patch is responsible for doing any actions
that are necessary to properly replace any older patch.”…””}”(hj<  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KPhj*  ubh¸)”}”(hŒ”As a result, it might be dangerous to replace newer cumulative patches by
older ones. The old livepatches might not provide the necessary callbacks.”h]”hŒ”As a result, it might be dangerous to replace newer cumulative patches by
older ones. The old livepatches might not provide the necessary callbacks.”…””}”(hjJ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KShj*  ubh¸)”}”(hŒìThis might be seen as a limitation in some scenarios. But it makes life
easier in many others. Only the new cumulative livepatch knows what
fixes/features are added/removed and what special actions are necessary
for a smooth transition.”h]”hŒìThis might be seen as a limitation in some scenarios. But it makes life
easier in many others. Only the new cumulative livepatch knows what
fixes/features are added/removed and what special actions are necessary
for a smooth transition.”…””}”(hjX  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KVhj*  ubh¸)”}”(hŒ¤In any case, it would be a nightmare to think about the order of
the various callbacks and their interactions if the callbacks from all
enabled patches were called.”h]”hŒ¤In any case, it would be a nightmare to think about the order of
the various callbacks and their interactions if the callbacks from all
enabled patches were called.”…””}”(hjf  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Xv  There is no special handling of shadow variables. Livepatch authors
must create their own rules how to pass them from one cumulative
patch to the other. Especially that they should not blindly remove
them in module_exit() functions.

A good practice might be to remove shadow variables in the post-unpatch
callback. It is called only when the livepatch is properly disabled.”h]”(h¸)”}”(hŒèThere is no special handling of shadow variables. Livepatch authors
must create their own rules how to pass them from one cumulative
patch to the other. Especially that they should not blindly remove
them in module_exit() functions.”h]”hŒèThere is no special handling of shadow variables. Livepatch authors
must create their own rules how to pass them from one cumulative
patch to the other. Especially that they should not blindly remove
them in module_exit() functions.”…””}”(hj~  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K`hjz  ubh¸)”}”(hŒŒA good practice might be to remove shadow variables in the post-unpatch
callback. It is called only when the livepatch is properly disabled.”h]”hŒŒA good practice might be to remove shadow variables in the post-unpatch
callback. It is called only when the livepatch is properly disabled.”…””}”(hjŒ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Kehjz  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j~  hjó  ubeh}”(h]”h ]”h"]”h$]”h&]”jÎ  jÏ  uh1jy  hŸh¶h K@hjï  ubah}”(h]”h ]”h"]”h$]”h&]”uh1js  hŸh¶h K@hjÞ  hžhubeh}”(h]”Œlimitations”ah ]”h"]”Œlimitations:”ah$]”h&]”uh1h¡hh£hžhhŸh¶h K>ubeh}”(h]”Œ!atomic-replace-cumulative-patches”ah ]”h"]”Œ#atomic replace & cumulative patches”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¶  jQ  jN  jÛ  jØ  j±  j®  uŒ	nametypes”}”(j¹  ‰jQ  ‰jÛ  ‰j±  ‰uh}”(j¶  h£jN  hãjØ  jT  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.