\}sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget*/translations/zh_CN/livepatch/system-statemodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget*/translations/zh_TW/livepatch/system-statemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget*/translations/it_IT/livepatch/system-statemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget*/translations/ja_JP/livepatch/system-statemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget*/translations/ko_KR/livepatch/system-statemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget*/translations/pt_BR/livepatch/system-statemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget*/translations/sp_SP/livepatch/system-statemodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhsection)}(hhh](htitle)}(hSystem State Changesh]hSystem State Changes}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhD/var/lib/git/docbuild/linux/Documentation/livepatch/system-state.rsthKubh paragraph)}(hSome users are really reluctant to reboot a system. This brings the need to provide more livepatches and maintain some compatibility between them.h]hSome users are really reluctant to reboot a system. This brings the need to provide more livepatches and maintain some compatibility between them.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hX!Maintaining more livepatches is much easier with cumulative livepatches. Each new livepatch completely replaces any older one. It can keep, add, and even remove fixes. And it is typically safe to replace any version of the livepatch with any other one thanks to the atomic replace feature.h]hX!Maintaining more livepatches is much easier with cumulative livepatches. Each new livepatch completely replaces any older one. It can keep, add, and even remove fixes. And it is typically safe to replace any version of the livepatch with any other one thanks to the atomic replace feature.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hXCThe problems might come with shadow variables and callbacks. They might change the system behavior or state so that it is no longer safe to go back and use an older livepatch or the original kernel code. Also any new livepatch must be able to detect what changes have already been done by the already installed livepatches.h]hXCThe problems might come with shadow variables and callbacks. They might change the system behavior or state so that it is no longer safe to go back and use an older livepatch or the original kernel code. Also any new livepatch must be able to detect what changes have already been done by the already installed livepatches.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hhhhubh)}(hLThis is where the livepatch system state tracking gets useful. It allows to:h]hLThis is where the livepatch system state tracking gets useful. It allows to:}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh block_quote)}(h- store data needed to manipulate and restore the system state - define compatibility between livepatches using a change id and version h]h bullet_list)}(hhh](h list_item)}(h=store data needed to manipulate and restore the system state h]h)}(hhjubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]jHjIuh1j hhhK>hjubeh}(h]h ]h"]h$]h&]uh1jhjDubeh}(h]h ]h"]h$]h&]jHjIuh1j hhhK7hj@ubah}(h]h ]h"]h$]h&]uh1jhhhK7hjPhhubeh}(h]livepatch-system-state-apiah ]h"]1. livepatch system state apiah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h2. Livepatch compatibilityh]h2. Livepatch compatibility}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKBubh)}(hThe system state version is used to prevent loading incompatible livepatches. The check is done when the livepatch is enabled. The rules are:h]hThe system state version is used to prevent loading incompatible livepatches. The check is done when the livepatch is enabled. The rules are:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKDhjhhubj)}(hXk- Any completely new system state modification is allowed. - System state modifications with the same or higher version are allowed for already modified system states. - Cumulative livepatches must handle all system state modifications from already installed livepatches. - Non-cumulative livepatches are allowed to touch already modified system states. h]j )}(hhh](j)}(h9Any completely new system state modification is allowed. h]h)}(h8Any completely new system state modification is allowed.h]h8Any completely new system state modification is allowed.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKGhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hkSystem state modifications with the same or higher version are allowed for already modified system states. h]h)}(hjSystem state modifications with the same or higher version are allowed for already modified system states.h]hjSystem state modifications with the same or higher version are allowed for already modified system states.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKIhj ubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hfCumulative livepatches must handle all system state modifications from already installed livepatches. h]h)}(heCumulative livepatches must handle all system state modifications from already installed livepatches.h]heCumulative livepatches must handle all system state modifications from already installed livepatches.}(hj'hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKLhj#ubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hPNon-cumulative livepatches are allowed to touch already modified system states. h]h)}(hONon-cumulative livepatches are allowed to touch already modified system states.h]hONon-cumulative livepatches are allowed to touch already modified system states.}(hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKOhj;ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]jHjIuh1j hhhKGhjubah}(h]h ]h"]h$]h&]uh1jhhhKGhjhhubeh}(h]livepatch-compatibilityah ]h"]2. livepatch compatibilityah$]h&]uh1hhhhhhhhKBubh)}(hhh](h)}(h3. Supported scenariosh]h3. Supported scenarios}(hjjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjghhhhhKSubh)}(hLivepatches have their life-cycle and the same is true for the system state changes. Every compatible livepatch has to support the following scenarios:h]hLivepatches have their life-cycle and the same is true for the system state changes. Every compatible livepatch has to support the following scenarios:}(hjxhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKUhjghhubj)}(hX\- Modify the system state when the livepatch gets enabled and the state has not been already modified by a livepatches that are being replaced. - Take over or update the system state modification when is has already been done by a livepatch that is being replaced. - Restore the original state when the livepatch is disabled. - Restore the previous state when the transition is reverted. It might be the original system state or the state modification done by livepatches that were being replaced. - Remove any already made changes when error occurs and the livepatch cannot get enabled. h]j )}(hhh](j)}(hModify the system state when the livepatch gets enabled and the state has not been already modified by a livepatches that are being replaced. h]h)}(hModify the system state when the livepatch gets enabled and the state has not been already modified by a livepatches that are being replaced.h]hModify the system state when the livepatch gets enabled and the state has not been already modified by a livepatches that are being replaced.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKYhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hwTake over or update the system state modification when is has already been done by a livepatch that is being replaced. h]h)}(hvTake over or update the system state modification when is has already been done by a livepatch that is being replaced.h]hvTake over or update the system state modification when is has already been done by a livepatch that is being replaced.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK]hjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(h;Restore the original state when the livepatch is disabled. h]h)}(h:Restore the original state when the livepatch is disabled.h]h:Restore the original state when the livepatch is disabled.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK`hjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hRestore the previous state when the transition is reverted. It might be the original system state or the state modification done by livepatches that were being replaced. h]h)}(hRestore the previous state when the transition is reverted. It might be the original system state or the state modification done by livepatches that were being replaced.h]hRestore the previous state when the transition is reverted. It might be the original system state or the state modification done by livepatches that were being replaced.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKbhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hXRemove any already made changes when error occurs and the livepatch cannot get enabled. h]h)}(hWRemove any already made changes when error occurs and the livepatch cannot get enabled.h]hWRemove any already made changes when error occurs and the livepatch cannot get enabled.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKfhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]jHjIuh1j hhhKYhjubah}(h]h ]h"]h$]h&]uh1jhhhKYhjghhubeh}(h]supported-scenariosah ]h"]3. supported scenariosah$]h&]uh1hhhhhhhhKSubh)}(hhh](h)}(h4. Expected usageh]h4. Expected usage}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKjubh)}(hlSystem states are usually modified by livepatch callbacks. The expected role of each callback is as follows:h]hlSystem states are usually modified by livepatch callbacks. The expected role of each callback is as follows:}(hj*hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKlhjhhubh)}(h *pre_patch()*h]j)}(hj:h]h pre_patch()}(hj<hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj8ubah}(h]h ]h"]h$]h&]uh1hhhhKohjhhubj)}(hX- Allocate *state->data* when necessary. The allocation might fail and *pre_patch()* is the only callback that could stop loading of the livepatch. The allocation is not needed when the data are already provided by previously installed livepatches. - Do any other preparatory action that is needed by the new code even before the transition gets finished. For example, initialize *state->data*. The system state itself is typically modified in *post_patch()* when the entire system is able to handle it. - Clean up its own mess in case of error. It might be done by a custom code or by calling *post_unpatch()* explicitly. h]j )}(hhh](j)}(hAllocate *state->data* when necessary. The allocation might fail and *pre_patch()* is the only callback that could stop loading of the livepatch. The allocation is not needed when the data are already provided by previously installed livepatches. h]h)}(hAllocate *state->data* when necessary. The allocation might fail and *pre_patch()* is the only callback that could stop loading of the livepatch. The allocation is not needed when the data are already provided by previously installed livepatches.h](h Allocate }(hjZhhhNhNubj)}(h *state->data*h]h state->data}(hjbhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjZubh/ when necessary. The allocation might fail and }(hjZhhhNhNubj)}(h *pre_patch()*h]h pre_patch()}(hjthhhNhNubah}(h]h ]h"]h$]h&]uh1jhjZubh is the only callback that could stop loading of the livepatch. The allocation is not needed when the data are already provided by previously installed livepatches.}(hjZhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKqhjVubah}(h]h ]h"]h$]h&]uh1jhjSubj)}(hDo any other preparatory action that is needed by the new code even before the transition gets finished. For example, initialize *state->data*. The system state itself is typically modified in *post_patch()* when the entire system is able to handle it. h](h)}(hDo any other preparatory action that is needed by the new code even before the transition gets finished. For example, initialize *state->data*.h](hDo any other preparatory action that is needed by the new code even before the transition gets finished. For example, initialize }(hjhhhNhNubj)}(h *state->data*h]h state->data}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKvhjubh)}(hlThe system state itself is typically modified in *post_patch()* when the entire system is able to handle it.h](h1The system state itself is typically modified in }(hjhhhNhNubj)}(h*post_patch()*h]h post_patch()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh- when the entire system is able to handle it.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKzhjubeh}(h]h ]h"]h$]h&]uh1jhjSubj)}(huClean up its own mess in case of error. It might be done by a custom code or by calling *post_unpatch()* explicitly. h]h)}(htClean up its own mess in case of error. It might be done by a custom code or by calling *post_unpatch()* explicitly.h](hXClean up its own mess in case of error. It might be done by a custom code or by calling }(hjhhhNhNubj)}(h*post_unpatch()*h]hpost_unpatch()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh explicitly.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK}hjubah}(h]h ]h"]h$]h&]uh1jhjSubeh}(h]h ]h"]h$]h&]jHjIuh1j hhhKqhjOubah}(h]h ]h"]h$]h&]uh1jhhhKqhjhhubh)}(h*post_patch()*h]j)}(hjh]h post_patch()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hX6- Copy *state->data* from the previous livepatch when they are compatible. - Do the actual system state modification. Eventually allow the new code to use it. - Make sure that *state->data* has all necessary information. - Free *state->data* from replaces livepatches when they are not longer needed. h]j )}(hhh](j)}(hICopy *state->data* from the previous livepatch when they are compatible. h]h)}(hHCopy *state->data* from the previous livepatch when they are compatible.h](hCopy }(hj4hhhNhNubj)}(h *state->data*h]h state->data}(hj<hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj4ubh6 from the previous livepatch when they are compatible.}(hj4hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj0ubah}(h]h ]h"]h$]h&]uh1jhj-ubj)}(hRDo the actual system state modification. Eventually allow the new code to use it. h]h)}(hQDo the actual system state modification. Eventually allow the new code to use it.h]hQDo the actual system state modification. Eventually allow the new code to use it.}(hj^hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjZubah}(h]h ]h"]h$]h&]uh1jhj-ubj)}(hdata* has all necessary information. h]h)}(h;Make sure that *state->data* has all necessary information.h](hMake sure that }(hjvhhhNhNubj)}(h *state->data*h]h state->data}(hj~hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjvubh has all necessary information.}(hjvhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjrubah}(h]h ]h"]h$]h&]uh1jhj-ubj)}(hNFree *state->data* from replaces livepatches when they are not longer needed. h]h)}(hMFree *state->data* from replaces livepatches when they are not longer needed.h](hFree }(hjhhhNhNubj)}(h *state->data*h]h state->data}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh; from replaces livepatches when they are not longer needed.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhj-ubeh}(h]h ]h"]h$]h&]jHjIuh1j hhhKhj)ubah}(h]h ]h"]h$]h&]uh1jhhhKhjhhubh)}(h*pre_unpatch()*h]j)}(hjh]h pre_unpatch()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h|- Prevent the code, added by the livepatch, relying on the system state change. - Revert the system state modification.. h]j )}(hhh](j)}(hNPrevent the code, added by the livepatch, relying on the system state change. h]h)}(hMPrevent the code, added by the livepatch, relying on the system state change.h]hMPrevent the code, added by the livepatch, relying on the system state change.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(h'Revert the system state modification.. h]h)}(h&Revert the system state modification..h]h&Revert the system state modification..}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]jHjIuh1j hhhKhjubah}(h]h ]h"]h$]h&]uh1jhhhKhjhhubh)}(h*post_unpatch()*h]j)}(hj.h]hpost_unpatch()}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj,ubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h- Distinguish transition reverse and livepatch disabling by checking *klp_get_prev_state()*. - In case of transition reverse, restore the previous system state. It might mean doing nothing. - Remove any not longer needed setting or data. h]j )}(hhh](j)}(h[Distinguish transition reverse and livepatch disabling by checking *klp_get_prev_state()*. h]h)}(hZDistinguish transition reverse and livepatch disabling by checking *klp_get_prev_state()*.h](hCDistinguish transition reverse and livepatch disabling by checking }(hjNhhhNhNubj)}(h*klp_get_prev_state()*h]hklp_get_prev_state()}(hjVhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjNubh.}(hjNhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjJubah}(h]h ]h"]h$]h&]uh1jhjGubj)}(h_In case of transition reverse, restore the previous system state. It might mean doing nothing. h]h)}(h^In case of transition reverse, restore the previous system state. It might mean doing nothing.h]h^In case of transition reverse, restore the previous system state. It might mean doing nothing.}(hjxhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjtubah}(h]h ]h"]h$]h&]uh1jhjGubj)}(h.Remove any not longer needed setting or data. h]h)}(h-Remove any not longer needed setting or data.h]h-Remove any not longer needed setting or data.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjGubeh}(h]h ]h"]h$]h&]jHjIuh1j hhhKhjCubah}(h]h ]h"]h$]h&]uh1jhhhKhjhhubhnote)}(hX*pre_unpatch()* typically does symmetric operations to *post_patch()*. Except that it is called only when the livepatch is being disabled. Therefore it does not need to care about any previously installed livepatch. *post_unpatch()* typically does symmetric operations to *pre_patch()*. It might be called also during the transition reverse. Therefore it has to handle the state of the previously installed livepatches.h](h)}(h*pre_unpatch()* typically does symmetric operations to *post_patch()*. Except that it is called only when the livepatch is being disabled. Therefore it does not need to care about any previously installed livepatch.h](j)}(h*pre_unpatch()*h]h pre_unpatch()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh( typically does symmetric operations to }(hjhhhNhNubj)}(h*post_patch()*h]h post_patch()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh. Except that it is called only when the livepatch is being disabled. Therefore it does not need to care about any previously installed livepatch.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubh)}(h*post_unpatch()* typically does symmetric operations to *pre_patch()*. It might be called also during the transition reverse. Therefore it has to handle the state of the previously installed livepatches.h](j)}(h*post_unpatch()*h]hpost_unpatch()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh( typically does symmetric operations to }(hjhhhNhNubj)}(h *pre_patch()*h]h pre_patch()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh. It might be called also during the transition reverse. Therefore it has to handle the state of the previously installed livepatches.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubeh}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]expected-usageah ]h"]4. expected usageah$]h&]uh1hhhhhhhhKjubeh}(h]system-state-changesah ]h"]system state changesah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerjKerror_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourcehʌ _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}nameids}(j%j"jjjdjajjjju nametypes}(j%jjdjjuh}(j"hjjPjajjjgjju footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]transform_messages] transformerN include_log] decorationNhhub.